This post is a part of How To Ship Maintainable Product series
Documentation is one of the most overlooked assets in a software project. We tend to assume that working software is our finish line. We don’t need any software documentation to run our business… until something breaks or somebody else needs to change software behaviour.
Preparing documentation is also a low-priority task. If it’s ever done, developers spend little time on it and don’t pay too much attention to cross-validate it. Updating documentation is even worse.
Where is the know-how?
The best time to validate our project documentation comes after the key developer leaves the organization. If things slow down, the error rate grows, customers complain more often, etc. something is happening. This may be a symptom of missing knowledge about the system. The know-how person has left the building. Forever. The organization failed to successfully transfer his knowledge to the others.
How much to document?
If we finally figure out that we need documentation we blindly ask developers to document everything. But what is ‘everything’? Each project is different and usually requires an individual approach for documentation too. Here are some areas that should be considered:
- Technical decisions
- Used patterns/solutions
- Customer configuration (business rules, etc)
- Environment configuration
Technical decisions
Technical decisions are very useful in postmortem discussions. The team can elaborate on why a particular approach was taken and what alternatives were considered. It’s very good for traceability.
Used patterns/solutions
Solutions should be simple. If they are not, a bunch of (possibly adjusted for our needs) software development patterns is applied to achieve the goal. This leads to a number of unique constructions that work and nobody knows why. Probably the current solution is optimal (we would know that if we have Technical decisions document), but extending it may be difficult. That is why all this should also be documented.
Customer configuration
This is usually applicable to support/operations departments. Consultants do changes on customer site. They create custom reports, tweak business rules, change permissions or firewall rules etc. Skipping documentation, in this case, introduces an unknown state of the system installed at the customer. Next time another consultant will have troubles understanding what is where and how is this system configured.
Environment configuration
Environment configuration covers various areas: development environment, CI/CD environment, DEV/TEST/UAT/PROD solution environment. The configuration of identified critical areas should also be documented.
Documentation types
Another aspect of documentation touches who is the documentation user. Here we can identify two cases:
- technical documentation - how things work technically. Operates on details.
- business documentation - how things work logically. Operates on abstraction.
Documentation advice
Picture vs text
Image is worth 100 words - where possible use pictures. They are easier to grasp and understand. The problem with pictures is that after project UI is changed it will take time to update documentation.
Give examples
It’s a good practice to provide examples on how to use API or particular functionalities. Also providing default config files is appreciated.
Use Markdown
If your documentation system allows some easy and standardized way to create documentation, use it. Documentation is much easier to maintain if it’s created in an organized way. Markdown is one of the systems I find very useful and simple.
Documentation update routing
Having a maintainable software requires having documentation that is up-to-date. Introduce a repeatable way for updating documentation.
Automate if possible
As I wrote in Automation - save your valuable time automating documentation generation will save you a lot of time.
Final words
The value of documentation is undervalued. Mostly because in most cases documentation takes time and we don’t see any benefits from that investment. Although, if you want to have a maintainable software, up-to-date documentation is a must.