Documenting Code with Code

On a regulated software project, especially one regulated by a government body, design documentation is a must.  It proves that designs were thought out and not developed in an ad hoc fashion, and captures key considerations made when the software was developed so that future developers, who may not have been part of the original project, are able to safely perform maintenance.

There are two popular methods for creating design documentation.  One method is to use tools like Word and Visio to manually create documentation.  This method gives the writer absolute control over the contents of the document.  However, this document will likely repeat documentation already found in your C# XML comments.  Also, creating Visio diagrams by hand can be tedious and time consuming.  And just because the documentation is being written doesn't mean the design won't change.  In many Agile environments, hand written documentation will likely be obsolete the minute it is published.

Another method involves using a documentation generation tool, like doxygen for example.  Tools like this extract documentation from code and format it as html, a pdf, etc.  Because documentation can be generated on the fly, it will always be relevant.  However, its really only good as reference documentation -- without sequence diagrams or textual design summaries providing context it would be difficult for a developer to understand the code for maintenance purposes.  For those tools that can automatically generate object model diagrams and sequence diagrams from code, how will it know what level of detail is sufficient?  How can it possibly have enough understanding of the code to diagram things into meaningful compartments.  To get all of the benefits, but none of the drawbacks, a documentation tool that resides somewhere in the middle is needed.

Instead of either of the previous methods, build a documentation generation framework where documentation is generated from code.  More precisely, the documentation IS code.  Think about it:

• Don't ever hand draw diagrams - use code to describe them and have the framework generate them.  Include as much or as little detail as is needed.
• Generate your documentation with every build - use strong types within the documentation so your build will break if it isn't up to date which means your documentation is never obsolete.
• Incorporate your C# comments at will.
• Allow for blocks of text - they can accompany diagrams to provide in-depth descriptions.
• Tweak your framework to completely change the look and style of your generated documentation in one fell swoop.