Technical Documentation – Outline for Technical Software Documentation

Probably not the answer you are looking for, but I don't want to have to read a technical document to understand an application.

In my opinion, the most important piece of documentation for a project is the unit tests! Whenever I come across some code I don't understand the importance of, I check the test cases. Clear and comprehensive tests can speak volumes about what the code is used for, along with all the other great benefits.

One problem with technical documents, is that they become obsolete very quickly. As features get added, and source code is refactored, maintaining documentation becomes a big hassle.

Technical documents should be geared towards your clients, users, or business partners, not your developers.

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.