[jroseattle]

I'm a documentation zealot. My eng teams understand we treat docs as products; they are project deliverables, and we allocate time to ensure we produce and maintain concise, clear and unambiguous content about the services we operate.

Nonetheless, I always have those team members who insist it's not their responsibility. A recent exchange I had with one of our engineers:

  Eng: I can create our entire service portfolio, but I just don't know how to explain it in a document.

  Me: I see. How about we start small, and just simply explain how service 'A' works. It's not too complicated.

  Eng: Well, I don't know what outline to use. I don't know how to publish it. I don't know what content I should add. I don't know who would read it. This will take too long. It feels like busy work.

  Me: So, if you're unable (seems like it) or unwilling (hopefully not) to do this work, what would you suggest we do to ensure we inform the rest of the company about service 'A'?

  Eng: I don't know.

  Me: Until we DO know, service 'A' will not be deployed.

[marcinzm]

So (based on their questions and your non-answer) you're not telling them the format, the audience, the goal of the document or how it will be consumed? And wondering why they're pushing back?

edit: And instead of answering their very reasonable and pertinent questions you instead accuse them of being either incompetent or lazy.

[jzb]

I'm struggling to understand how somebody can be responsible for creating a service but not understand who the audience is for reading its documentation. Some of the questions may be reasonable (one would hope if documentation is a requirement there's at least a standard format, etc.) but "it feels like busy work" and "this will take too long" destroy the premise that this is about not having answers to reasonable questions.

How do you know how long something is going to take if you don't know the format, etc.? Calling something "busy work" is sort of signal that this isn't "I need help getting started" it's "I'm trying to weasel out of this."

[marcinzm]

>I'm struggling to understand how somebody can be responsible for creating a service but not understand who the audience is for reading its documentation.

Documentation can be read by product managers, managers, QA engineers, engineers on call, engineers integrating with the service, and engineers taking future ownership of the service. Which group(s) it is depends on company dynamics, culture and processes. Documentation written for the PM of another team may be nearly useless for someone on call trying to triage a bug. Documentation lifecycle also matters since otherwise you will just get useless stale and inaccurate docs. However if it's a product manager focused documentation then you may have no choice however if it's engineer focused you may want to bake most of it into code (swagger, etc.). Just document it is how you get the 99% of documentation that is never read by anyone in the future.

[jroseattle]

Allow me to clarify a few things:

- Format: we don't dictate format on docs. In terms of sharing important information, it's irrelevant. Dealer's choice.

- Audience: we are writing documents that are internal to our team, but also for consumption by other groups. Audience is engineering-focused.

- Consumption: we refer to documents as a way of learning all the things before asking uninformed questions to team members. RTFM is an expectation in my groups.

> instead of answering their very reasonable and pertinent questions you instead accuse them of being either incompetent or lazy.

These expectations aren't random; they are well-known, part of project deliverables, and non-negotiable. Existing projects show the quality of what's been produced in the past, to help with an understanding for anyone documenting what they've built and want us to depend on in production. After that, we definitely help those who still require help, but this isn't a surprise.

[marcinzm]

>Allow me top clarify a few things:

It was your story written by you on how you interact with engineers. I'm not the one you should be clarifying things to.

edit: The read I get is that a number of engineers fundamentally disagree with the value of your approach. As they're the ones who should be getting value from it based on your clarification that's a very bad sign.

[jroseattle]

I was thinking you were asking questions and/or engaging to understand, of which I've made an incorrect assumption.

[tqi]

"I don't know how" is the helpless version of the question that lazy children use to get out of shit they don't want to do. "Is there a audience I should write for / template I should use" is the clarifying version of the question someone who actually intends to do something asks.

[crazygringo]

I read it the exact opposite, that the engineer is just being difficult, especially with the last three: "I don't know who would read it. This will take too long. It feels like busy work."

I mean, who do you think is going to read it? Obviously anyone who needs to interoperate with the service.

And the first three parts, let's address in turn:

"Well, I don't know what outline to use." Whatever outline other documentation at the company uses.

"I don't know how to publish it." So ask somebody who has published documentation how they do that.

"I don't know what content I should add." Look at pre-existing documentation and use that as a model.

I mean, this isn't rocket science here. This is clearly somebody obstructing things -- somebody who doesn't want to be a team player.

If, as an engineer, you can figure out how to set up git to make a commit, you can figure out how to publish documentation. It's entirely inappropriate to be using up your manager's time asking them to hand-hold you through this, when you can just ask a fellow team member to send you the resources you need.

This isn't elementary school -- it's a professional work environment where you've been hired for your expertise and your ability and initiative to solve basic daily problems on your own. The dialog as presented does portray the engineer as either lazy or incompetent, no question about it.

[marcinzm]

"I want you to figure out how to document things to my specific standards but I won't spend time to document the process I want."

[wahnfrieden]

This is why companies are starting to replace more middle manager roles with ICs

[gloryjulio]

I don't understand, how is this even possible? If we don't understand:

1. the problem that we are solving 2. the input data 3. the process flow 4. the outcome

how do you even start coding?

[danrl]

As and engineer, sometimes getting started is the hardest part. But there are high quality, open source templates for almost anything in the documentation process available. I wish initiatives like The Good Docs Project would be more popular with engineers.

https://thegooddocsproject.dev