Documentation

Documentation is important. If you can spend one hour writing a simple text that will cut the learning curve in half for ten other people, then that is well invested time. Write documentation on several different levels, aimed at different audiences.

When developing with the architecture in the center, lots of good opportunities for documentation will be created. Languages and components are ideal documentation candidates.

There is a large number of useful documentation just waiting to be written.

• Source code documentation
• UML diagrams
• Component design documentation
• Component usage documentation
• Language descriptions
• User manuals
• Architecture description
• Build and release instructions
• Installation and configuration instructions

The first rule of source code documentation is that the code should be its own documentation. Well written code is often quite easy to understand. Make sure you use a well defined vocabulary throughout the code and be careful with the naming of classes, methods and variables.

To complement the code, it is usually good to write embedded comments using Javadoc or Doxygen. The main purpose of these comments is to describe the intention of methods and classes. This documentation is then automatically extracted and compiled into a hyperlinked document.

UML diagrams can also be generated from the code. If you want UML diagrams that cover the code in detail, this is the preferred way to create them. Avoid detailed UML models that must be updated manually.

Languages and components are ideal documentation candidates. By focusing on documenting them, your documentation will cover the entire system on a useful level. Focus on language descriptions, component usage and component design.

It is important to document components. An engineer searching for components to reuse must quickly be able to determine the scope and functionality of a component. Otherwise the risk is high that he will dismiss the component on false grounds and rewrite it from scratch himself.

Documenting the architecture is obviously important in architecture centric development. The architecture description will be a document that constantly evolves as the system is developed.

There are two kinds of documentation for the user. The first consists of manuals describing user interface languages. The second consists of installation and configuration documentation.