Hidden costs of poor or lacking documentation
In programming, reliable documentation is always a must. The presence of good documentation helps keep track of all aspects of an application, library or platform and it improves the quality of a software product. It makes it possible to transfer knowledge to other developers, help the support-team understand how the software works and makes it possible to maintain the product.
Imagine that as a developer, you don’t document your work. Then each developer that needs to work on your software may have to spend hours or days (and a lot of frustration) to dig in your undocumented code, search the code-base and ask you for clues and help (if you are still around in the company..). When spending a few hours to document your code, you will save each of these developers a couple of hours or even days of work. This, ultimately, will save all developers that need to work on your code a lot of time which we can be spent doing actual work.
Now imagine that besides not documenting our code, we have not written any good documentation about our software or code at all. No high level overview of how the software works, no description of how all parts fit together or even what the exact purpose of the software or component is.
You will want to avoid this situation at all costs, as it would be next to impossible for a support-team to support the software this way. They will need to bother the developers for every small technical question they get – countless hours will be ‘wasted’ this way.
On top of this, it will be a very tedious and long process getting new developers in the team onboarded and up to speed to become productive contributors.
Worst of all, if a developer decides to leave the company – all the knowledge about the software (which was in his/her head) will leave with him/her.
So, not only does lack of good documentation add an enormous cost to the software development process, it also poses a huge risk and business liability for the company when developers decide to leave and knowledge about the software is lost.
(Image copyrights https://sciencereport.dk/)
Creating good documentation
A lot of developers don’t like commenting code and documenting their work. They find it boring and it takes a lot of time. However, in order to make your work usable for others, either as code or in the form of a library or framework you really need to pay attention to this.
Successful documentation will make information easily accessible, provide a limited number of user entry points, help new users learn quickly, simplify the product and help cut support costs. Here are some points to consider when creating documentation:
- Structure. Your code should be well structured and neatly commented. Regularly take time to clean up redundant parts of the code. Ensure your API’s stay consistent. Don’t be afraid to refactor code to improve readability and clarity. Don’t use dirty tricks which are hard to understand for others. Keep in mind that you only write the code once, but it will be read often. Spending a little extra time to make your code better readable and maintainable will most likely pay off, not only for others but also for yourself.
- Documentation: The more developers use your work, the more it will pay off to spend some effort on documenting your library. Suppose you don’t document your work. Then each developer that needs to work on your software may have to spend hours or days (and a lot of frustration) to dig in your undocumented code and ask you for clues and help. If you spend a few hours to document your code, you will save each of these developers a couple of hours work. This, ultimately, will save all developers together a lot of time which can be spent doing actual work.Good documentation consists of the following parts:
- A high level overview of how your library works, how all parts fit together, explaining the flow of the program.
- A set of tutorials, helping a developer to get up and running with your software.
- A set of examples, demonstrating how to use your component/library/code in practice.
- Detailed documentation describing any API’s of your software. This should be fairly easy to generate when you neatly document your code.
- Setup. No matter how good your documentation is, when the process to get your software up and running is a 14 step process which takes hours and requires a lot of knowledge and pre-conditions – most people will give up. It should be a no-brainer to get your code / library / framework up and running. If not, developers will give up and either ask you for help all the time or create support tickets. Writing a getting-started tutorial helps a lot in making clear what an installation exactly needs.When your software is complicated to get up and running, this may be a sign that something is wrong. If that is the case, take a step back and figure out what makes it so complicated. Try to eliminate these complex requirements and ensure a smooth first experience with your software.
You can be a brilliant programmer and write genius code. However, if you don’t make your work accessible and usable for others, your code will most likely have a limited use, and will die as soon as you’re no longer in the neighbourhood to baby-sit and maintain it. Put a little extra effort in documenting your code and make it easy for other developers to get started with your code. This will drastically increase the applicability of your code, and makes the life of developers much more fun.
I’m sure you prefer to use applications and libraries which are well documented and supported, so take these as an example when writing your own.
Do you have any tips on how to document software in a good way? Or do you have ideas on what absolutely NOT to do when creating documentation?
Write it in a comment below!
