Even the simplest, cheapest home appliance comes with a more or less detailed user manual. Most of us decide to throw it away and trust in the good design of the device for discoverability1, allowing us to learn how to use it. But right after design, good documentation sets the difference between a piece of junk and a helpful piece of equipment. Every once in a while, we find ourselves rummaging through kitchen drawers or searching the internet for instructions to find that specific setting for the washing machine or the oven to achieve our desired results.
Unlike in nature, the human world is replete with detailed instructions. From the cave drawings depicting a handy “how to slay a mammoth in 4 simple steps” to the present day, we’ve been striving to describe every aspect of our surroundings and our activities, presenting them in a way that anyone can learn without needing to bother us. Laziness and a desire for tranquility are the most powerful engines of progress. You can probably agree with me when I say that I would do almost anything to avoid a 9:00 am call asking how to fix [put your domain-specific problem here]. I would even go so far as to write some documentation for it!
Documentation is a game changer
It’s not just an opinion; year after year, the State of DevOps Report has consistently highlighted the substantial benefits of GOOD documentation in nearly every key aspect measured (well, at least since 2021, but it’s still revealing, don’t you think?). The difference between starting a new job in a place where even finding the restroom is an adventure and one with a comprehensive onboarding process that thoroughly introduces you to every aspect of daily work at the company, from the important to the trivial, is substantial. By alleviating that cognitive load, you can become productive much sooner.
Amplify technical capabilities with quality documentation2
High-quality documentation amplifies the impact that technical capabilities have on organizational performance. Trunk-based development, for example, is estimated to have 12.8x more impact on organizational performance when high-quality documentation is in place relative to low-quality documentation.
State of DevOps Report 2023
If documentation is so valuable, why do we consistently struggle to create it? Primarily, this is because in our industry, there seems to be a deep-seated tradition of undervaluing it. Partly, it’s due to the startup and hustle culture, where there’s a focus on achieving immediate results by cutting out all the ‘unnecessary’ steps to get from point A to point B as quickly as possible. It reveals a significant deficiency in professionalism and craftsmanship, I must admit. However, the main reason we often fail is that it’s a challenging task: we’re not skilled at it!
Here’s a list of problems and tips that I have identified and personally experienced to some extent over the years regarding why documentation is challenging:
The Novice vs Expert Dilemma
The more you understand, the harder it is to explain. The more you know, the harder it is to document.
When you’re new to something, you easily understand the need for documenting it, both for your future self and for the sake of others. However, at this stage, you may still lack the knowledge to provide a detailed explanation. You’re also in a process of discovery, so the pieces may appear scattered as you attempt to put them into words on the fly. While you’re investing all your time and energy into learning, you may not have as much time to dedicate to recording your findings. It’s no wonder that people often give up after some initial attempts to document something new they are working on or investigating, as previous failures can be discouraging. Consequently, you may end up with little to no documentation or documentation that is of poor quality in these cases.
Experienced workers, on the other hand, possess knowledge and a deeper understanding after dedicating a significant amount of time to a specific activity. Unfortunately, they often hold crucial roles, and their time is deemed too valuable for management to even consider assigning them what is all too often viewed as a mundane, low-skilled job, such as writing documentation. When they do find the time to dedicate to it, they may struggle to simplify the complexity enough for a beginner, as they already perceive the activity as easy, or they may delve into a technical discourse too advanced for a newcomer. Entrusting documentation to senior employees can result in a similar outcome, ranging from nothing to a document that only a few people can benefit from.
Tip:
- Documentation as a team effort: Create a culture where less experienced team members collaborate with their more senior counterparts on documentation. This collaboration can take various forms, including promoting reviews, pair documentation, and more.
The impostor syndrome
Even after many years of programming and working in software development, most of us still battle with the sensation of not being good enough. We fear that someone may discover we’re impostors if they find even the slightest inconsistency in our documentation. Are you telling me that after struggling for days to make this work, I have to backtrack and explain how I did it? I wish I knew!
Tips:
- Positive Feedback: Ensure that team members receive regular positive feedback on their work, including their documentation efforts. Recognizing their contributions can help reduce self-doubt.
- Self-Reflection: Encourage self-reflection and regular reviews of one’s accomplishments. Often, individuals with Impostor Syndrome discount their achievements.
- Set Realistic Expectations: Help team members set realistic expectations for themselves. Nobody is perfect, and nobody knows everything. It’s okay to seek help or admit when you don’t know something.
I don’t get paid to document
Yes, too many developers prance around without the slightest idea of what they’re paid for. Do you? In my humble opinion, this is nothing but a silly excuse. You get paid to be professional, not to whine around. You may not like that part of your work, and I understand that, but it is not only beneficial for the rest of your team—by documenting something, you enhance your understanding of it and improve your communication skills. Last but not least, you should be documenting even when working alone: be considerate of your future self.
Tips:
- Peer Accountability: Encourage team members to hold each other accountable for documentation. Peer reviews can include assessing the quality and completeness of documentation.
- Educate on the Value of Documentation: Start by emphasizing the importance of documentation in the software development process. Explain how it improves team efficiency, knowledge sharing, and the quality of the final product.
- Lead by Example: Leadership and senior team members should lead by example. When they prioritize documentation, it sets a positive precedent for the rest of the team.
Words don’t come easy
Even the most accomplished experts may find it extremely difficult to put into words something that comes naturally to them. Like a geeky version of Cyrano, some of us are gifted with skills that others lack. To some extent, I must concede this point: we’re not all equal, and we can’t expect everybody to excel at everything. There’s nothing wrong with that. However, if you feel the desire to surpass yourself and overcome your limitations, there’s nothing to lose and a lot to gain from it.
Tips:
- Documentation Templates: Create templates that guide in structuring documentation. These templates should prompt for essential information and encourage a consistent format.
- Documentation Workshops: Host workshops or training sessions for team members to teach them effective documentation techniques.
- Documentation Tools: Invest in documentation tools that make it easier for everyone to create and maintain documentation. Tools with templates, version control, and collaboration features can be especially useful.
I mostly refer to written documentation, but images, diagrams, videos, and primarily (in the context of us as programmers) well-structured, self-explanatory, clean code™ are other means of documentation. I strongly encourage you to try and enhance your skills and advocate for the practice of documentation within your team and organization. It’s worthwhile—doc and code!
Leave a Reply
You must be logged in to post a comment.