Let us take a quick moment to first figure out what documentation is in the context of software development. You can be building any kind of software and it's guaranteed to have some sort of documentation in place regardless if it's internal software or a licensed one.  

Documentation is essentially an instructions manual to any software you are working on or building. The better the instructions manual is the faster you can get started. This applies to all manuals or documentation.

Developer workflow

Before we go to the bread and butter of the headline it is also crucial to look at a developer’s workflow. You could call the state a developer enters a flow where they hold all aspects of the tasks they are doing in their mind. This is where the creation happens – interrupt at your own peril or rather with a cost.

Entering a particular state for humans can take up to 30 mins if interrupted by somebody or by needing to do something that isn’t related to the task at hand.

Example of bad documentation

Let’s circle back to the quality of the documentation and take a real-world example that everyone can relate to. Ikea. You could argue that their instructions to build their furniture is moderately easy regardless of what it is. This is a good documentation where it has examples in the simplest of terms – pictures.

Now what is an example of bad documentation? Imagine building an Ikea furniture but instead of getting a step-by-step guide with pictures you get just a list of items in the box and a promise of what it can look like.

Not really something you’d like to experience, right? Then why are we making developers face this all the time?

Cost of bad documentation

There are few aspects where bad documentation ends up being extremely costly. You might still be asking why documentation matters. If you are doing one-use software in a small company. Let's look at those examples from different aspects.

New developer onboarding

Onboarding a new team member is always great. They bring fresh ideas and a pair of eyes that aren’t blinded by the stuff you have been working on. Also it does require effort from the team to get them up to speed with things. The smoother the onboarding the faster they can start performing and developing features. 

A lot of the knowledge transfer happens in terms of questions, reading the code and documentation related to it. After a while of doing this they will start developing their first user story. 

The hurdle comes if the documentation isn’t great. They will need to ask a lot of questions from the team and from other related software teams. This will interrupt others' work, their work and start piling up. Essentially you lose velocity. Same goes for when they start debugging. 

If you are looking for fast growth, bad documentation will really hurt your development velocity for quite some time. 

Multiple end users

Imagine if you have multiple teams using your software. They all have questions to which they need answers. This will seriously hinder the development speed of the software you are doing when your developers need to answer similar or same questions over and over again. 

When the huge majority of those questions could be answered by good documentation. Freeing time for working on new features and increasing the development velocity of the whole organization. 

Especially applies to software companies selling it to external customers. Here is when the documentation is a key for fast growth of the organization. 

If you are developing an internal software then you might think why don’t the team using your software do the documentation? Reason for this is 2nd hand knowledge of what they have gained while developing. It might work in terms of their use cases but leaving the majority of use cases out as well as the fundamentals of it. 

Maintenance

Maintenance of software is another chunk of work that is often outsourced. Here the documentation plays a key role also when the people maintaining aren’t too familiar with the software. They rely on the documentation to debug issues that happen sometimes in the dead of the night. I am doubting you will be answered questions during that time unless otherwise agreed. 

Documentation is a key player in the maintenance of the software and ensuring it runs smoothly 24/7. The Internet doesn’t rest. Imagine a software that isn’t available throughout the day. Doesn’t sound appealing does it? 

Great documentation vs Bad documentation in pictures

‍

With great documentation it is faster and easier to onboard new developers, maintenance becomes easier and can be partially outsourced to different companies or units and for end users a description of what does what makes them ask less from the development team. Often internal softwares don't have documentation or the quality is poor which leads to the following case.

VS

When you have been pushing of doing documentation it leads to a lot of additional load for development team in terms of questions on how things work. Which always removes time from doing further development. Sometimes it is good to have few questions here and there from new people using it so you can find new areas to develop.

Wrapping of thoughts 

All the costs from the lack of good documentation usually end up on the team building on top of your software, continuing to build your software or using it to fill a part of their software (like in eCommerce it could be product recommendations). 

Ease of use is critical no matter who your end user is. If it is deemed to be too time consuming or complex to use you generally start losing users. We pay so much attention to our customers that we sometimes forget the people internally.

Measuring the cost of lackluster documentation can be challenging and time consuming in itself. So it ain’t easy to have others see it. Money speaks always....so if you have done the measuring and can showcase it. You can bring a business case forward to budget time for documentation not having to just develop more features and worry more about maintenance or team retention. Its like a delicate cardhouse where glue could be great documentation.

Great documentation doesn't mean overly detailed documentation which takes again time from development. There needs to be balance as in everything to keep velocity up.

Great documentation just makes sense, doesn’t it?