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.
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.
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 building 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 a bad documentation? Imagine building an Ikea furniture but instead of getting a step-by-step guide you get just a list of items in the box and a promise of what it can look like.
Not really an alluring example is it?
Cost of bad documentation
There are few aspects where bad documentation ends up being extremely costly. You might still be asking why does documentation matter 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 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 bugs.
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 fundamentals of it.
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
Wrapping of thoughts
All the costs from the lack of good documentation usually end up on the team building on top of your software or using it to fill a part of their software (like in eCommerce it could be product recommendations).
If it is deemed to be too time consuming to use you generally start losing customers. Ease of use is critical no matter who your end user is. We pay so much attention to our customers that we sometimes forget the people making that possible.
Measuring of 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 – things are bound to change.
Great documentation just makes sense, doesn’t it? Or did I fail to paint a clear picture for this? As usual I am open to discuss these and let me know!