Software deserves documentation

Building software is a tough process. A lot of disciplines are involved to specify the requirements, to define the software architecture, to manage the data, to test, to integrate and to run the software and possibly to do a lot more thinks. Different processes - from waterfall to agile - try to handle these tasks in different ways and they produce different documentation artifacts.

But sometimes the process is less informal and things just get done and work. This is not bad but documentation is often neglected in this sczenario. However, as a developer I think (my) software deserves a documentation. And the documentation that I can provide is mostly related to the software architecture. Therefore I used templates like the Software Architecture Document (SAD) of the Rational Unified Process (RUP) or the Arc42 template form the arc42 project in the past. I like these templates because they remind me on the key information that I can (should) provide about the software. But they most often are over complicated and contain topics that I do not need to handle or miss topics that are relevant for me. So I need to modify these templates over and over again.

Thus I decided to create my own Software Documentation Template. It should be simple but fit my daily needs better than the ones mentioned above. The topics handled in this document should make it possible

• to maintain the software
• to use the software
• to integrate and operate the software

The template also should be simple enough to encourage other people in the team to use it for their software components as well.

All that said, my template looks similar to other architecture document templates but it only includes top level chapters. Few content hints should describe what information can be included in a section. All the rest (like further sub chapters) depend on the concrete project and should be configured as required.

Software Documentation Template

1. Introduction
   Purpose of the software, Context / Scope, References 
2. Software Lifecycle Managemen
   Version Control, Issue Management, Quality Management
3. Requirements
   functional, non functional 
4. Concepts
   Communication (with other components); Security, Internationalization 
5. Implementation
   Overview, Concepts, Significant Details 
6. User Interface / API
7. Data
   Storage, Access 
8. Deployment
   Installation, Configuration 
9. Operation
   Start, Stop, Monitoring, Exception Handling

A document based on this template should provide enough information to enable development and operation to do their work – without writing long description emails or having long discussions anymore.

How to prevent the documentation from aging

Once written documentation starts aging. My best advices to prevent the documentation from aging are

• Do not document the details if not needed. They may change more often and it is hard to keep the documentation actual. Better document the overall concepts that are needed to understand the “big picture”. It should be possible to get the details from the code than.
• Do not repeat information that is basically maintained elsewehere. E.g. if your software needs some configuration properties that are provided in a property file in your version control system just link to this file (most VCS offer some kind of browser access) and do not repeat the properties in the documentation.

Improvements / Feedback

I am confident that the template will fit most of my needs. Nevertheless there is always place for improvements. I therefore created the GitHub project SoftwareDocumentationTemplate to enable template changes.

I would love to get your feedback on this topic. My main goals are to keep the template complete but simple and to protect documentation from aging. Any thoughts on this are very welcome.