Mastering the Art of Documentation
Documentation is really just glorified dog sitting
Welcome to the first installment of my series on soft skills essential for succeeding in the tech world. If you're interested in this series, don't forget to subscribe or follow me on X/LinkedIn/YouTube (videos coming soon). -Logan
The largest, most overlooked area of effective software developer communication is documentation. No one likes writing documentation because we feel like it takes away from the fun part of the job: coding. In reality, overlooking proper documentation costs us more coding time in the long run due to time spent troubleshooting lost information. The purpose of this article is to:
Guide you through what good documentation entails.
Make it so you don’t dread writing it.
Make your teammates love you a little bit more due to your well-documented code.
Documentation is Communication
For those new to software development, documentations (or "the docs") are where software engineers go to learn about a technology. Documentation encompasses the necessary knowledge needed to understand and use software. Whenever software is written, the accompanying docs much be written also to use and maintain it.
But what if I'm the only one using my project? Document it! Your future self revisiting a project after five months might struggle to understand what's going on. Consider your future self as another developer who has never even heard of the project before. You'll be doing yourself a favor by documenting your code while your knowledge is still fresh. Trust me, current Logan has gotten upset with past Logan many times for failing to do this.
If you build software in a team, there are expectations regarding documentation. You are expected to be both a writer and reader of documentation. As a writer, you are expected to write and maintain the docs for the code you create and work on. They should be unambiguous and contain all details necessary to maintain and work on the code. As a reader, the docs are the first place you should look for answers— this is why writing high-quality documentation is critical. As a reader, if you come across documentation that is inadequate, make it better.
The Dog Sitting Analogy
To understand proper documentation, let's imagine you're writing instructions for someone to care for your dog while you're away. You'd need to provide detailed instructions that anyone unfamiliar with your dog could follow easily: feeding times, walk schedules, specific care instructions and so on. You’d turn taking care of your dog into a simple algorithm.
Writing documentation follows a similar principle. You need to provide comprehensive, step-by-step instructions that anyone unfamiliar with your project can follow to use or continue developing it. An important part of this is to never assume the reader has any prior knowledge of the project or technologies used. I learned this lesson the hard way when I was working at Microsoft because my initial documentation was almost unusable. I learned that even though C# and .NET are all the over the place at Microsoft, I should never assume the reader had any level of proficiency in them.
Documentation Goes Beyond Markdown Files
One common issue when I'm reading documentation is that many engineers only focus on the source code when documenting a service. This is particularly true in corporate software engineering when the documentation is for internal use only. Documentation for production code involves more than just documenting code itself. It also needs the tools for maintaining the service such as:
links to servers, logs, rollouts, and work to be done
links to tests and how they function
an explanation of how rollouts, monitoring, and alerting work
contact information for additional information
CLI commands
the why of the project and links to any documents used during the planning stage
which on-call rotation is in charge of that code (if applicable)
Would you ask your dog sitter to walk your dog while you’re away and forget to give them a leash? No! So don’t ask someone to maintain a service without the proper tools to do so. Simply put, if there's a resource you visit while working with the service/code, include it in the documentation.
A Single Source of Truth
Something that makes documentation very difficult to maintain is when its spread across multiple locations. Just as you would put out your dog’s leash on the counter to make it easy for the dog sitter to find, make information about your service easy to find. Keeping the docs in one place makes them easy to find reducing miscommunication between engineers.
This source of truth should be checked into a version controlled system. Not only does this remove the risk of losing your all of your documentation if it accidentally gets deleted, it also forces your teammates to review any documentation you add. The best way to find holes in documentation is to have many eyes on it. As an area expert, it can be very difficult to write documentation detailing even the most basic understanding of a product or service. This is made much easier by having non-domain expert teammates take a look at it.
Keep Your Documentation Up-to-date
At Google, our documentation includes metadata displaying the owner and the last review date at the top of each document. If a document isn't updated regularly, a red exclamation point alerts the reader. I think this is overkill. Documentation doesn’t need to reviewed just because it’s old—it needs to be reviewed when the service it details has changed.
An easy way to maintain your documentation as code is updated is to treat it like tests. When updating your code, don’t just ask “Does this update require more tests?” but also ask yourself "Does this update need documentation?"
The other time documentation will need to be updated is when a bug is found. Documentation should be updated to detail the process of troubleshooting the bug and make the fix easily accessible for future reference. When bugs appear (and they will), write down how they were fixed in detail and make that information available to everyone within the documentation.
Writing Documentation Step-By-Step
Here’s an easy step-by-step to ensure your documentation isn’t missing information. Start with this information:
What is it? Describe what the service/product/code does, its users, and why it was designed that way.
What resources do you need when working on it? Include links you visit when you work on and maintain the service and explain their relevance. This means dashboards, logs, monitoring, etc.
Who has worked on this before? Include contacts with background knowledge in this area.
Document any commands you run or actions you take to maintain the service.
Include any additional relevant information that may be needed for development and maintenance.
Also, proofread your documentation. Re-reading it takes five minutes and you’ll clarify many mistakes and ambiguities.
Conclusion
Every developer needs to learn how to write effective documentation. It's a skill that takes practice, but it's well worth the effort. Good documentation can make the difference between a project that's a joy to work on and one that's a constant source of frustration. So, take the time to hone your documentation skills. Your future self (and your teammates) will thank you.
Spotlight
This week I’d like to spotlight an awesome article written by
in . I think a lot about how social media isn’t really social and even encourages dishonesty. Devansh has an incredible take on this topic and more in his article here:
Thank you for reading all the way to the end and supporting my writing! Don’t forget to subscribe. If you’re already a free subscriber, you can upgrade to paid for just $5/mo. Paid articles and other benefits are coming soon.
Appreciate the spotlight. Great piece. Did a piece on documentation a while back that was interesting to a lot of people. Might be useful to you- https://codinginterviewsmadesimple.substack.com/p/how-to-create-good-documentation?utm_source=substack&utm_campaign=post_embed&utm_medium=web