Never the most glamorous of topics. However good quality internal documentation for development teams can be a driver of efficiency. Good documentation is often a sign of a healthy development team that takes pride in their work. It has benefits for team productivity in the long term by removing the bottleneck around individuals who have a lot of knowledge of the system. Often there is a member of the team that spends much of their time helping other people to understand how the application works or the reasons why things are done in a certain way. What happens if this person moves to a different team or even leaves the company?

In an ideal world code is self-documenting and easy to understand. This is the argument often put forward by developers when asked to write documentation. However, in the real world this is rarely the case:

• Code is often too complex to understand by just reading it.
• Legacy code may not have been written to the same standards as greenfield code or has deteriorated over time.
• Concepts could be spread over multiple files, increasing the complexity of trying to understand it.
• Reasons behind nuanced decisions that were made during development are lost, such as performance-sensitive implementations.

Documentation of standards and practices is equally important. Over time, teams decide on preferred ways to do things, whether the structure of an application, design patterns for specific problems or libraries to help with processes. Such decisions should be documented and easy to find so that engineers can make the right choices early on during the development process. Determining at the point of code review that something doesn't follow team standards is inefficient and a waste of development time. Moreover, it is important for team members to be able to work with a degree of independence, particularly in the world of hybrid working where what used to be a short conversation with the person next to you has now turned into a phone call and therefore is more disruptive to the workflow of both people.

When creating documentation, it is important to empower everyone, regardless of experience. If only senior engineers are contributing, then details could be too complex for more junior team members or assume a level of knowledge that may not yet be achieved by all readers. Everyone should be encouraged to fill in any gaps in their knowledge.

So how can this be achieved? Make documentation a part of the development process. Is documentation part of the team's “Definition of Done”? Can a task be created for each pull request to encourage the writer to make any changes? With each change, ask the following questions:

• Is there a new feature that others should know about?
• Has something changed in an already-documented feature?
• Was information needed for development missing?
• Was an important decision made that should be shared with others?

Let's help our future selves!

Andrew Main, Senior Software Entwickler, INTEGRATE Informatik AG