Skip to content

re: What makes maintaining documentation difficult? VIEW POST

re: 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 ...

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.

code of conduct - report abuse