The main reason documentation gets skipped is because it is writing the same code twice. You write it once in a programming language and once in a human language. Then you have two places to maintain. When the pressure is on to deliver something, only programming language really needs to be updated to get the functionality. But when you skip updating the documentation, it becomes ever more daunting to go back and straighten it out.
In a previous team, there was a dedicated documentation person (tech writer) who made sure the documentation stayed up to date with the changes that were happening in the sprint. The tech writer split their time with multiple teams because it was not a full time effort for any individual team.
That was really the only way that I have seen to make sure documentation gets updated consistently. Make a person primarily responsible for it.
I think that's one of the hardest things for me. I really want to believe that my code is clean enough to document itself so I don't need to write as much actual documentation, but it will naturally get messier and harder to read over time that that's when I start to wish I had written that documentation in the first place.
It's a really great idea, having a team member fully-devoted to keeping documentation up-to-date. I've been following Netlify closely for a couple months, and I was really impressed when I found @verythorough
does exactly that for Netlify. I'm sure this would be a difficult thing to convince upper management to devote resources to, but what practical benefits have you experienced that would help convince them for a team wanting a full-time documentation writer/engineer?
You first have to consider who the documentation is for. For that team I was on, the documentation was for the user. It described how to accomplish things with our application. It also encompassed release notes. So it was not integrated into code at all. It was stored and updated in a separate system and generated for each release.
If you are documenting the API of your library, the situation is a bit different. Most devs will expect documentation that pops up in their editor when they hover over it (or something similar). Devs typically have to write this embedded-in-code documentation. Then if necessary, more exhaustive documentation, usage guidelines, and further examples might be available on the website. The website could be based on the code comments initially, but these are not typically the best format for users to read through. So then you end up with supplemental documents that are not embedded in code to make for a better documentation UX. Like an Introduction section describing the product at a high level and providing an organization structure to drill into specific topics. Eventually documentation should become a first class product on its own, doubling as a support tool (and maybe a sales aid, so potential users can evaluate the product capabilities for their needs). While the code comments become more of an appendix. A first class documentation product probably won't happen accidentally while the team is really focused on something else. It is going to need a dedicated team in the long run. But perhaps not all library / API products need to go this far.
The value of having a dedicated tech writer depends on the product. If you provide a public API / library and make money from it, I would think a tech writer would not be a hard sell in the long term. If it is an internal tool, that can be difficult to convince people unless it is already in the corporate DNA. The value there is more limited.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
The main reason documentation gets skipped is because it is writing the same code twice. You write it once in a programming language and once in a human language. Then you have two places to maintain. When the pressure is on to deliver something, only programming language really needs to be updated to get the functionality. But when you skip updating the documentation, it becomes ever more daunting to go back and straighten it out.
In a previous team, there was a dedicated documentation person (tech writer) who made sure the documentation stayed up to date with the changes that were happening in the sprint. The tech writer split their time with multiple teams because it was not a full time effort for any individual team.
That was really the only way that I have seen to make sure documentation gets updated consistently. Make a person primarily responsible for it.
I think that's one of the hardest things for me. I really want to believe that my code is clean enough to document itself so I don't need to write as much actual documentation, but it will naturally get messier and harder to read over time that that's when I start to wish I had written that documentation in the first place.
It's a really great idea, having a team member fully-devoted to keeping documentation up-to-date. I've been following Netlify closely for a couple months, and I was really impressed when I found @verythorough does exactly that for Netlify. I'm sure this would be a difficult thing to convince upper management to devote resources to, but what practical benefits have you experienced that would help convince them for a team wanting a full-time documentation writer/engineer?
You first have to consider who the documentation is for. For that team I was on, the documentation was for the user. It described how to accomplish things with our application. It also encompassed release notes. So it was not integrated into code at all. It was stored and updated in a separate system and generated for each release.
If you are documenting the API of your library, the situation is a bit different. Most devs will expect documentation that pops up in their editor when they hover over it (or something similar). Devs typically have to write this embedded-in-code documentation. Then if necessary, more exhaustive documentation, usage guidelines, and further examples might be available on the website. The website could be based on the code comments initially, but these are not typically the best format for users to read through. So then you end up with supplemental documents that are not embedded in code to make for a better documentation UX. Like an Introduction section describing the product at a high level and providing an organization structure to drill into specific topics. Eventually documentation should become a first class product on its own, doubling as a support tool (and maybe a sales aid, so potential users can evaluate the product capabilities for their needs). While the code comments become more of an appendix. A first class documentation product probably won't happen accidentally while the team is really focused on something else. It is going to need a dedicated team in the long run. But perhaps not all library / API products need to go this far.
The value of having a dedicated tech writer depends on the product. If you provide a public API / library and make money from it, I would think a tech writer would not be a hard sell in the long term. If it is an internal tool, that can be difficult to convince people unless it is already in the corporate DNA. The value there is more limited.