Why it matters

The word "documentation" comes from Latin and means "to teach" or "to prove". This is exactly what we need documentation for in software projects. It should enable the project team - the main user of the documentation base - to search for trustworthy and up-to-date information on their own. The bottom line is that weather you are a developer or a project manager you need to keep track of information, decisions and changes as the project grows.

Done wrong, the opposite happens and you end up with a sea of documents that only long-term experts can navigate to find the information they need. There are certain patterns that indicate when documentation is no longer of value to the customer - the project team.

What can go wrong?

• Outdated Information: As a project grows, information becomes outdated. This may be due to lack of time and approaching deadlines and/or lack of motivation to keep one's part of the documentation up to date. Over time, new people join the project, teams grow, and information starts to spread across multiple pages. Some is not maintained, or wording starts to change between teams. In the end, it becomes difficult to identify the source of the truth. Only people who've been around for a while can find their way around using custom search patterns, while newcomers struggle to find what they need and end up creating more documentation. It has now become a waste of time and, in the worst case scenario, decisions are being made on the basis of outdated information.
• What goes where: Another problem is the location of the documents. Storing technical documentation far away from the code itself encourages outdated information. Tools such as Notion, Trello or Confluence may be good for ADR tracking, but not for maintaining detailed architectural discussions and documentation. If documentation is not updated after refactorings, it will become outdated and useless over time, increasing the onboarding time for new colleagues and further polluting the documentation base.
• Sea of Sources: Often the sheer number of sources used to store and maintain documents becomes a problem. Sharepoint, Wiki, network drives, Dropbox, local drive, ... The list goes on and on, and often they are all used in parallel as sources for documentation. Documents get scattered between sources until only the project's document ranger is able to track down the latest requirements document from the customer.
• The Chaos: If you end up with a flooded documentation base, you may want to refactor. Simply apply a new structure to clear up the cloud of data and make the documentation useful again. Of course, like refactoring legacy code, this is a huge investment of time. And it is likely to end up being an even bigger mess if deadlines get in the way, or if there is no clear set of rules about how to deal with the documentation in the project after the refactoring.

How to do it right!

In my experience, documentation should be treated by the whole project team like a product itself - it needs constant work and attention. Here are some best practices I've learned along the way:

• Keep it organised: Clear structure and ownership are key. Reduce the number of places where documents can be created and maintained - less is more. The structure should be agreed by the project team and ensured through a review process.
• Make it easy to find: As projects grow, make sure it's easy to find what you need. The most important way to achieve this is through vocabulary. The more effort you put into maintaining a common language and using a common vocabulary, the less time you will waste explaining words. In the future, AI will make it easier to find information, but having a common language in the first place will also improve the AI's results.
• Control what's added: Not everyone should be able to add new documentation into tools without checking them first. Have a review process in place to make sure everything fits together, which will result in information being merged rather than duplicated and outdated. But please avoid documentation blockages caused by a small number of owners and vacations.
• Keep it close to the code: To avoid outdated technical documentation, keep it close to the code. Using Markdown files with embedded UML diagrams, such as PlantUML or Mermaid, will greatly improve the quality of a repository. It links the architecture documentation directly to the code, helping to keep everything together. This way, everyone on the team can easily update the documentation as they work on the code, and it is directly integrated into the review process.
• Increase motivation: Applying the previous practices will result in documentation that feels manageable. Many team members are reluctant to maintain documentation. Small process steps and a time-efficient review process will reduce the time cost and overcome the barriers to doing their bit. This will increase motivation to contribute not only to a product for the customer, but also to a valuable product used by the team.

In short, think of documentation as a product you're always working on. If you keep the technical documentation close to the code, have a clear structure and rules, and make it easy to find, you'll end up with documentation that is actually useful and easy to maintain.