Internal product documentation

Question

We have a system that has grown over a number of years (ASP.NET Web Forms, MySQL) and we're looking for guidance on what to document about it and how to document it so that we have a single place we can go to understand how the system should behave.

This documentation would allow both developers and testers recognize what might be affected as we make changes.

We are building out comprehensive unit tests, but that effort is still in progress, and I don't believe that the unit tests will be a good, readable description of what the system does.

How have people documented the functionality and behavior of a system? What tools do you use? Who is responsible for the documentation? Do you organize it by screen? By scenario?

Answer 1

I find Doxygen quite useful for documentation. (It supports C# if that's the language you're using.) As far as who is responsible, I think the correct answer is that all developers should be responsible. Doxygen (and many other documentation tools) have options to produce warnings for code which is not documented.

Any developer should always check that a full set of documentation can be produced before committing code. Even with a fairly large project, this should only take a couple minutes to check and resolve. This is much easier than having someone else go back later and try to figure out what's going on.