You know it: an old project gets reactivated because your customer needs a new feature or has found bug. Meanwhile, the responsible developers have been reassigned to new projects and have no time to finish the task. You are currently not at a 100 percent workload so you get the task assigned. Because of the missing documentation you are busy with the setup of your development environment in the first few hours. After that you spend the next hours (days) with trying to understand the architecture of the application.

This is an experience every developer or system administrator has made for sure: There is no documentation available or the existing documentation is insufficient or outdated. Thereby an appropriate documentation would result in having more time which could be spent for development and testing.

Types of documentation

Besides the inline documentation of the source code and the end user manual other types of documentation exist. Unit and integration tests for example are a good basis for new developers to understand the internal API. Acceptance tests show how the application will be used by the customer and which typical workflows exist.

It does not matter if frameworks like FitNesse or Cucumber are used or everything is tested with “plain” JUnit/TestNG. The essential fact is that the tests document how the application or architecture can be used.

Furthermore, a developer documentation should exist so that new developers can easily incorporate into new projects. A developer documentation describes the basic topics which must be considered during the development process, for example:

• Where is the source code located? Which branching model is used?
• With which credentials can I access the development servers?
• How is th build process organized? How is Continuous Integration/Delivery realized?
• How to deal with schema migrations?
• Where are coding styles located?
• How did I properly set up my development environment?

As the developer documentation has only the developers as target audience and is only used for internal purposes, the architecture documentation could be although read from external persons. For example one of our customer claims a documentation about security-relevant processes and a documentation about the system and application architecture. The documentation about security relevant processes is required during a security certification, the system documentation is a requirement for the deployment in the datacenter.
In the best case the architecture documentation contains all desired information and can be simply forwarded to the customer.

The Ops needs a operational documentation which can be derived from the architecture documentation. The operational documentation contains topics like “Where can the logging be customized?” or “Where can I customize the database connection string?”.

Organisational and project relevant topics with non-technical background are discussed in the project handbook. The project handbook contains topics like repsonsibilities, contact cards, the processes for bugtracking and meeting notes and so on. Target audience for this documentation is the project management.

Include documenting in your company culture

The writing of documentation should be firmly established as central position in your company culture. New employees should seee on their first day at work that the corporate wiki contains all required information. The involvement in discussions and the improvement of existing documents is explicitly requested. This concept can only succeed if every coworker has already realized how important a good documentation is and leads by example.

In my opinion it is the duty of every good developer or administrator to document his work and his decisions. A good documentation makes the difference between a project and a professional project.

Therefore in our company the following dictum exists: “If it is not documented in the wiki or bugtracker it has not been done.”

Use the right tools

One of the biggest faults is the usage of the wrong tools. Making a good documentation means not using Word and Excel in first line. Instead push every information into your corporate wiki so that every project-related person has instantly access to it. I really like Confluence and can only suggest you give it a try.

Templates like arc42 are a really good start for the documentation. Try to make your own templates which are adjusted to your needs.

The right person for the right job

The development and architecture documentation should be written from the responsible architect during the the development of the concept. He knows the big picture and makes the technical decisions. Always document, what leads to your decisions!

The operating documentation can be written by the developers who implemented the application. The architecture documentation can be used as a basis. The internal system administrators should although read the documentation. They know at best which information is expected in such a document.

Writing the end user manual can be a chance for transfering the domain knowledge of the project to new employees who are not directly connected to it. This can only work if every team member is a aware of the fact that the documentation is an important component of a successful project. It is not a job which can be done by anyone. The requirements for writing a good end user documentation are high:

• Often, the manual ist the first contact between the customer and your application. The manual must be attractive edited und concentrated on the essential tasks of the application.
• Your customer does not care about any technical explainations in the end user manual. He reads the document because he has to fulfil his tasks. You are probably also not interested in how the wood was cut while you are building up your IKEA shelf.
• Your documentation is the reference book and will be the first shelter if any questions occur. Describe the functional processes.

A professional end user manual will demonstrate the customer that the application is elaborated and developed by professionals. A good end user manual is making a major contribution in the successful acceptance of your application.

Every document should be read early and regularly by other persons to reveal problems in the comprehension of the documentation.

Lessons Learned

• Introduce the documentation process as a central building block of your company culture.
• Use tools like Confluence or arc42 and build your own set of templates.
• Writing a good documentation is an art like programming is an art.
• Treat your authors with respect.
• Writing a documentation is like programming – only on a higher level.
• Don’t write a developer or architectural documentation after the project is done. Write it at the beginning of the project.
• Keep your documentation up to date.
• Documentation is an important component of your application.
• Documenting is a continuous process which has to be reviewed at the latest after the project has finished.

Footnote: If you liked the blog post, you would probably like Jens’ blog post about software documentation.