I've been doing a lot of research on the cost of bad software documentation, and came across this paper by C. J. Satish and M. Anand. It's a survey of various published works to indentify recurring pain points caused by bad documentation. One highlight: what happens when a developer leaves?
Losing Knowledge
Here's a quote from the paper:
Documentation is not complete and people who have the knowledge about the system retire without adequate knowledge transition.
The absence of original requirements documentation nullifies the option of rebuilding the system
You know that developer that has been in the team since day 1, for the last 8 years? The one that knows everything about the system, because they wrote a good chunk of it, but haven't written anything down.
Now, they are leaving the company, and are asked to write handover documents that explain how...wait for it... everything they've worked on for the last 8 years works. Oh, and their last day is this Friday and they have zero motivation or incentive to actually do a good job documenting things.
Don't Leave It To The Last Minute
The worst time to start worrying about documentation is when the knowledge is about to be lost forever.
There is a very real cost in not documenting our internal systems as software engineers. In the best case, developers lose a few hours a week tracking down how a system works, and in the worst case, huge amounts of knowledge are simply lost as people leave the company over time.
As I was about to write this, I came across this relevant quote about how long it takes for a developer to ramp up in a new team.
A $60K/annum employee may very well take $120K before reaching the productivity level and contribution of the developer who left the team.
To decrease that number, invest in your documentation. Make it a first class citizen in your process. Ask for doc updates in code reviews, just like unit tests. Invest in your tools. Otherwise your developers will turn into
archaeologists.
While you're here, If this resonated with you, you might be interested in what I'm working on. Head on over to my personal site if you want to reach out or hear more.
Top comments (0)