Documentation – Who Should Write Technical Documentation?

documentation

At first, I thought that the people writing the code should also document it. But there are reasons why this might not be true. A person who is new to the code could ask the right questions which might be dismissed as "obvious" by the author.

My question is if there is an established practice (or practices), and what is the reasoning behind it/them?

Best Answer

It sounds like you're making the assumption that the documentation is written once and never updated. That may be true if your software never changes after it has been written, but that's probably not the case. Just like you can refactor your code to improve readability and maintainability, your documentation should also be in a format the promotes the ability to refactor. Your initial code authors are good candidates to write the initial documentation, but the people who maintain the code will also need to maintain the documentation. If the existing authors are still around and are answering questions from the new maintainers, someone (either the original authors or the new maintainers) should be assigned the task of making sure that the documentation is more complete.

The exact breakdown of roles and responsibilities depends on the organization. In some places, the developers are responsible for anything in the code file (API documentation and in-line comments) and the developers and testers support technical writers who write and maintain documents. In other organizations, the development team may write everything.

At the end of the day, it doesn't really matter who writes and maintains the documentation, as long as it is maintained. After all, wrong documentation is quite possibly worse than not having documentation at all.

Related Topic