Documentation is a hot topic, and everyone has an opinion about it. If you rely on the quality of it, there is a linear relationship between the quality of the document and the simplicity of your task. If they task you with writing the required documentation, most likely you would like to finish that task as early as possible. Because that task is boring and you’d rather work on something exciting. Especially in startups, one skips documentation in favor of tasks that contribute directly to the product or service that will bring in the big bucks. Hence, the question, new feature or better documentation is usually a straightforward decision. But what are the hidden costs of such a decision?
Other Departments
You are part of the development team, but you are not the only department in the company. There are other teams that rely on the quality of what you documented during your development of a part or feature of the service or product. Crystal balls are scarce (you know, the 2022 supply chain issue and stuff). They don’t know what you know unless you have explained to them how you took the specification and translated it into an implementation. Sure, you can explain this to several people, but not all departments ramp up on your part of the product or service at the same moment in time. Chances are that you have to explain things several times to different departments. And they might have different questions. Because different departments need to know different things. That is exactly the reason documentation exists. You document something once and your colleagues from other teams in the organization take that as the input for their work.
Unavailable Colleague
When you are available to give explanations and to do Q&A-sessions, everything is still under control, albeit in a less efficient way. Maybe I can tell you a story that really happened to me many, many years ago. I had a colleague in another design center that worked on a chip design as the only designer. The chip was in production and the designer moved to other projects. Suddenly, they found a nasty bug in the field. Big red flag emails sent around the company, immediate bug fix needed. Unfortunately, a few weeks before they found the bug, the designer passed away. He never documented his work. There was only a specification, no design document. I was the lucky one that was available to dive into the design, find the issue, and fix it. That was a valuable life lesson regarding documents, I can assure you. Obviously, there are less extreme versions of unavailability. Your colleague can be on holiday or unavailable because of illness. Or your colleague resigns, which is a more permanent unavailability example. Then it all comes down to the quality of the person’s documentation. If it is bad, people and thus the company will lose otherwise valuable time. The question is if you want to run that unavailability risk or not?
Onboarding
Gallup found that about 12% of the employees strongly agree that their company does a great job of onboarding employees. Onboarding is much more than IT delivering a laptop or desktop to work on. You need to understand the product or service that is in development for months or years. That can be difficult if documentation is missing or incomplete. Not all employees will dare to ask the right questions or call out the problems in the documentation. The result -again- is a loss of valuable time.
Bugs
Let’s consider the verification of your service or product. Does it work? Does it have all the features? Do those features work according to the specification? These are all relevant questions. Of all defects found during development, we can trace 2 in 3 back to the requirements. The entire process of correctly documenting the requirements, the specification, the architecture and the design documents is crucial for the success of the verification. The overall quality of the verification can never be higher than the overall quality of the input documents. Hence, if you start with inferior quality input, you will for sure get inferior quality output.
Conclusion
Small companies with just a few employees have fewer issues with other departments because in the beginning there will be no or just a few departments. When your company grows to a few dozen employees, more departments form. Cooperation and transfer of knowledge become more important as all issues mentioned above come into play. They slowly strangle the efficiency of that startup company. Ultimately, it can be the differentiator between a successful and a failed startup.