What intention do you want to take into the new year? For many of us, the year rolling over is a good time to consider where we have spent our energy, and where we want to spend it next year.
For the coming year, I’d like to advocate for you spending more of your work energy on internal technical documentation—the documents that your team uses, not the ones you expect customers to use. Internal documentation is an enormous force-multiplier for your entire team, and we can see that from leading industry studies. For example, the "2021 Accelerate State of DevOps Report" found that teams with quality documentation are:
• 3.8 times more likely to implement security practices
• 2.4 times more likely to meet or exceed their reliability targets
• 3.5 times more likely to implement Site Reliability Engineering (SRE) practices
• 2.5 times more likely to fully leverage the cloud
If there was a tool that you could buy that would more than double the chances you’d hit your reliability goals, you’d buy it, right?
This is a good news/bad news situation. A tool like that exists, but you can’t buy it, you have to build it. Internal documentation is one of the few areas where it is not actually more efficient to try to purchase a solution, because the value is in how your organization acts and wants processes to work, and that’s not something you can import.
From Github's "State of the Octoverse Report":
“Developers see about a 50% productivity boost when documentation is up-to-date, detailed, reliable, and comes in different formats (e.g. articles, videos, forums).”
If it sounds intimidating to get started on creating or improving your documents, print out this treasure, also from the "Accelerate" report:
“Documentation doesn’t have to be perfect. Our research shows that any improvement in documentation quality has a positive and direct impact on performance.”
What is internal documentation?
Internal documentation comes in all flavors and sizes. For large organizations, they may hire professional technical writers to work with internal teams and publish on internal sites. For small-to-medium organizations, internal documentation can start with something as small as a readme, a runbook, or an onboarding email.
Documentation and declarative infrastructure can also run into each other and intertwine in a very DevOps-y organization. There is less to document if all you need to say is “install this image,” but as the installation or running instructions get more complicated, the documentation needs to grow with them.
Here are some kinds of internal documentation:
- Readmes
- Runbooks
- Setup instructions
- Process instructions, for everyday use or emergencies
- Reference documents, such as server passwords, configurations, or quirks
- Resource ownership (who do I ask about…?)
That’s not a complete set, but it may be enough to get you started thinking about what you already have, and what would be most useful to invest in first.
How does internal documentation help?
Internal documentation reduces friction for all the tasks you have documented and makes it easier to onboard new people, run procedures reliably under stress, detect and confirm automation opportunities, and most importantly, means that there isn’t a single point of failure in your organization. After all, it’s hard to go on vacation if you are the only person who knows how to do something crucial.
Internal documentation that is checked and agreed on is also a useful way to be sure that your organization is actually aligned. Simon Wardley says that a lot of the value of creating a Wardley map is not the map itself, but the process of discussing the contents and agreeing on it as a team. In the same way, discussing and revising internal documentation is a great moment to decide if a process is actually serving your team’s needs.
Finally, internal documentation serves as a place to record your thinking behind technology choices. Sometimes, it’s vital to understand why a decision was made so that you don’t reverse the underlying logic when you update it.
For example, imagine a thermostat with a “don’t touch” sign taped to it (we’ve all worked in that office). You know that you’re not supposed to change the temperature, because that’s what seems to be documented. Then one day someone goes to break the rules and change the temperature, and they find out it’s labeled “don’t touch,” because it’s conducting live current and it will shock you if you touch it! This is a case where the documentation exists, but it needs to be more complete. I’m sure you can think of similar, less-electrifying examples in your workplace.
What should I do next?
It’s hard to just decide to “do documentation.” Frequently, our organizational structures make it difficult or unrewarding to spend time on documentation instead of what our job descriptions say. Setting up your organization for documentation success requires buy-in from people in power as well as your team-members.
The "Accelerate State of DevOps" report suggests that to improve the chances of getting documentation:
- “Include documentation as part of the software development process. Teams that created documentation and updated it as the system changed have higher-quality documentation. Like testing, documentation creation and maintenance is an integral part of a high-performing software development process.”
- “Recognize documentation work during performance reviews and promotions. Recognition is correlated with overall documentation quality. Writing and maintaining documentation is a core part of software engineering work, and treating it as such improves its quality."
Selling your idea
One way to get buy-in from leadership is to demonstrate how much time/money documentation saves. How long does it take to complete a process now, before documentation? How long did it take to do the documentation? How much time does the documentation save for every time the process is repeated? How often is the process repeated?
For example, I once fixed a form from being a document that had to be hand-written and faxed into a fillable PDF. Doing that cost me about four hours. The savings was about 10 minutes per submission. We processed 200 claims a day. That’s a savings of 167 hours a week. If documentation reduces incidents, streamlines releases, or prevents errors, then it’s easy to make a case for rewarding people for doing it.
Resolved
You don’t have to make perfect documentation. It doesn’t have to look good. You just need to make documentation a habit, like you do with every resolution you want to keep.
Doing the work
With both internal and external documentation, it can be difficult to get started, but the process doesn’t have to be horrible. Individuals and teams don’t usually get time and resources allotted to documentation, and even if they do, they don’t know where to start. I felt so strongly about this that I helped write a book about it: “Docs for Developers.”
Getting some words down
In my previous experience as a technical writer, I usually started in one of two ways: either I did a full documentation inventory to find and collect all the existing documentation, or I started with whatever missing item was the largest impediment to daily operation. You can do the same thing, depending on your resources.
For an inventory, start with the documentation you know about, no matter how sketchy or partial. Ask your team members to do the same. Create a shared page with pointers to everything you know about. Don’t move anything right now, since people are probably relying on the current location. As you assemble the inventory, you’ll start to see gaps, or realize that some things are documented more than once. Work with your team to standardize the location and update the documents that you’ve found, as well as adding new documents to go with what you’re developing.
For the other method, sometimes it’s easy to identify the most painful gap or lack in documentation. Are you getting angry emails about your API documentation? That’s the place to start. Are you having production outages because your release process is partially oral history? That’s where you need documentation first. Create whatever minimal documentation you need to solve that problem. It doesn’t need to be pretty, or comprehensive, it just needs to work. Standardizing and templatizing can be next steps.
Making it automatic
Anyone can tell you that a routine is more likely to stick around than something that requires remembering. Tonight when you brush your teeth, you probably won’t have to deliberately remind yourself to do it; it’s just part of the “going to bed” routine. The goal is to make documentation that automatic— like hitting CTRL-S when you shift windows (what, I’m old), or getting a code review before you commit something, or running an integration test.
To make documentation automatic, make it part of the finish criteria. Does that feature have a readme? If not, it’s not done. Are the server settings documented? If not, it’s not actually done being built. This causes a lot of failures at the beginning, but people get accustomed pretty quickly, and making documentation a unit-level task means that it doesn’t get to the “too big and intimidating” stage as frequently.
Another way to make documentation more automatic and simpler is to use templates. If you have any existing documentation, you can use it to extrapolate what the important parts of a document might be and make it something people can fill in. If this sounds exotic or complicated, look around, because you’re probably already using templatized documents. Look at how you describe bugs in release notes, or error messages, or API calls. Those follow a formula, and you can find the formula in other types of writing. It’s a lot easier to fill in a Mad Lib page about how to do something than to think of each step and how you should phrase and order everything.
Maintenance
The only thing worse than not having documentation is having documentation that is wrong or misleading. To prevent that, your organization needs to have a process for checking back over documentation that exists and making sure it’s still correct. Ideally, if code changes, the docs change with it, but there are a lot of documents that aren’t about code. This might include:
- Third-party integrations
- Workflow and process
- Tools and destinations
- Ownership
Further resources
I already mentioned my book, but there are so many places you can find information about technical writing—Write the Docs has a conference series, Slack, and podcast. Google has free-to-all technical writing lessons. LinkedIn Learning and Pluralsight offer technical writing instruction.
The first job is to start.
Happy new year, and I hope this resolution sticks, because it’s going to super-power your team!
.webp)
