The importance of proper documentation to software development teams

What is documentation?

Many software teams tend to hide or run away from documentation even though it is essential and necessary. I like to define documentation as technical communication as it relates to software development. It is basically a description of the application, design or requirements of a software or product.

The two main aspects of documentation are documentation for communication and documentation for understanding.

Let’s say I have to plan a design, suggestion, or architectural decision. Before I do any work I always document everything down, step by step. In my documentation, I highlight how my design is going to be, who is going to be affected, what component is going to affect other components, etc. This showcases the aspect of documentation for understanding.

The other aspect, documentation to communication, simply means that documentation can be used to share information within a team.

The methodology and process of documentation is not something fixed and it depends on how a team is structured. For example, in Moniepoint Group we use agile methodology to be able to deliver products of quality, on-time and within budget. So as an agile team, we have to ensure that we maintain balance when it comes to documentation since it can become counterproductive if not kept quick and simple.

The need for documentation…

There is always going to be tension within the team if there is no documentation. One aspect of documentation, as mentioned before, is to be used as a means to communicate. So, if there is no documentation process, it means we have to rely on people’s memories.

Let’s say we have to make a new feature and things are not documented well enough. This can create tension within the team when a colleague creates something that does not align with what was discussed. It could be that they forgot to add an important feature, or they made an incorrect assumption. But if there was documentation, it could have been a guide of what we are trying to achieve.

A lot of times, documentation is overlooked at the start because people are in a rush to begin working. After a couple of days, one can realize that a person from the team had diverged from the goal because they didn’t understand things like everyone else.

Therefore, it is important to always write down the steps and everything that needs to be done first. This way, there are no ambiguous parts of the design.

I try to use documentation as an addition to the team, but not as an afterthought. I see it as something that will help, but not as a rigid step that we really have to do. Sometimes, documentation can be counterproductive if you use four to five hours on documentation. It clashes with the modern way we do software engineering.

One way to overcome this, is to use collaborative documentation. That way we can encourage discussion, requirement definition and documentation without wasting time writing documents when our goal is to deliver products.

Helpful tools and resources for documentation

There are many helpful tools and resources for modern day documentation in software engineering, like draw.io and lucidchart for UML diagrams, doxygen and sphinx for documenting software and various team workspaces used for knowledge sharing and collaboration, like confluence or nuclino.

You can choose whatever fits you team needs but remember, simple is better. Sometimes a markdown text is all you need!

Getting the team on board

Documentation is essential for the team. Therefore, everyone on the team has to know that there is a documentation process in place, irrespective of the size of the team.

One way to get everyone on board with the process is during stand up meetings. If anybody has a blocker, they share it during these meetings, so it’s the perfect time to let them know if there’s some documentation that could help. And if it doesn’t exist, you can create it, collaboratively if possible, and share with everyone.

Another helpful way of getting everyone on board is by ensuring that the documentation is available for all members of the team. These documents will be useless if they are stored locally on a PC. It defeats the aim of using documentation to communicate.

The documentation process from start to finish

When it comes to documentation, some teams may have a template already. So, if someone new joins the team, they can use the template to draft up the documentation for a process.

For me, if I’m creating a documentation process from scratch, the first thing I would start with is a short summary of the problem that we are facing. If it’s more complex, then we can add some context by giving a more detailed explanation of it. Afterwards, I would add the source of the problem, and may give a technical reason on why the problem exists.

Then we could also add what is out of scope so that no one gets lost. Sometimes, we have to state what technical requirements can (or should) be disregarded.

We can also document what the current solution is, past efforts, and even future goals, depending on how much time we have and how complex the problem is.

Finally, we go to the proposed solution. In a few lines, try to explain how we plan on tackling the issue. Here, we can also state if this solution has any conflict with other technical strategies of the team or if there are any dependencies impacting other software.

If it’s just the backend, we may have to add a few lines about the business logic, like what modifications we are trying to do in an API for example. We may also add some flow charts if it’s a large, complex project we are documenting. If it’s a UI, we can add a few notes about the presentation layer and also a few test cases.

On a final note

I know that some people feel the documentation is counterproductive as it seems to be taking time away from development. However, this only happens when you do not understand the aspects of documentation.

It’s time to start seeing documentation as a means of communication as well as understanding. So, before you start with the code, create simple but thorough documentation, share within the team and you’re good to go.

It’s better to lose half an hour to discuss and document something, rather than have to revisit the implementation and lose countless hours figuring out problems.