Documentation for engineers is a wonderful thing to have. As a new team member, I usually have a ton of questions. Many of those will need to be answered by a teammate — but whenever there’s a good doc for something, I breathe a sigh of relief.
But the docs run out pretty quickly. It turns out that writing and maintaining internal docs is pretty expensive, and harder than it looks. Here are some things to try the next time you’re in a position to document something.
1. Ask your teammates what to document
The best way to waste time writing docs is to write docs that no one reads.
Talk to people who are unfamiliar with your system and ask them what they find confusing about it. Strive to make your docs about the reader, not about you. This is a big part of why Stack Overflow is so useful to engineers. People with questions start the threads, not people with answers.
Listen especially to the questions that your new team members ask. These questions are probably very common across your organization.
2. Make your docs timely, not timeless
Do you have any docs that are out-of-date? I can definitely relate. When you publish a readme in a git repo, you’re making an implicit promise to update that readme whenever the related code changes. I think of these as timeless docs, because you’re never done writing them.
There’s another kind: a timely doc is one that you publish at single, clearly identified moment. You imply no promise to update it. Think of it as an immutable snapshot of how things work at a certain date.
Examples of timely docs are Stack Overflow comments, YouTube videos, and your Slack history. You can make any doc timely by simply writing a date at the top.
3. Link to each doc from at least three places
Most companies’ systems for searching internal documents are fragmented and unhelpful. If your doc isn’t linked to from three different places, it might as well not be there.
Some places you can try linking from:
- Your documentation directory (the root README)
- Your Slack channel
- A comment in an Asana task
- Source code comments
Make sure the text you use with the link contains terms that readers are likely to search for when they need your doc.
4. User test your docs
Sit down with a team member who isn’t familiar with your system and ask them to make some trivial change to it. Then, sit silently and observe, making sure to take notes.
- Don’t tell them about your docs — do they find them naturally while working on the system?
- Observe how they navigate through the document. Do they read it completely, or scan it?
- Do they copy and paste anything from the doc? Why or why not?
- Do they search for anything? Which terms do they search for?
- Which questions remain after they find your doc?
5. Treat your docs as prepend-only
Is there a new system phasing out an old one? You don’t need to edit all of the old docs, but you definitely should add a new intro or “banner” to the top of the old docs explaining where to find new ones.
Old docs accrue a lot of SEO in the form of links scattered across your team’s tools. They’ll be easier to discover than your shiny new docs for a while.
Clearly separate this banner from the rest of the doc with a separator line. This makes it obvious that the rest of the doc is not being kept up-to-date.
