I was recently talking to a coworker who is in the middle of a large project to document her job. The goal is two-fold: to give teammates the ability to cover for her when she’s out of the office and to improve the onboarding experience for new team members. She has her manager’s support, but it’s a large project. She finds it difficult to make progress, in part because she doesn’t particularly like writing. As a result, the deadline keeps slipping further out.
I won’t claim to be the best documentarian, but I try to always leave my successor with better documentation than my predecessor left me. I’d like to think I’ve succeeded in that. In some cases, the bar was pretty low because there was no documentation at all. At any rate, this post is a collection of things I’ve learned over the years. This is an opinionated post and does not necessarily represent the One True Way to Document Your Job™.
Writing
- Separate the why and the how. You have two separate audiences: someone filling in for a day or two and someone taking over the role. The information they need is very different. A person covering short-term probably doesn’t need or want to know the whole history of a process. They just want to know the steps they need to take. On the other hand, your replacement will benefit from a greater level of explanation. They’ll want to know why the steps are they way they are. In particular, knowing what didn’t work well in the past is a good reference to help them avoid re-learning that lesson later.
- Start at a high level. If you cover the broad stuff first, that gives your reader something to work with, even if they need to ask you or someone else to help fill in the details. On the other hand, a detailed list for process A does nothing to help with process B. Starting at a high level also allows you to…
- Write small chunks. You don’t need to write everything in a day. Starting with higher level concepts allows you to break the role into a few key areas. From there, you can break it down further and further.
- Limit the work in progress. Similarly, you don’t need to write everything at the same time. if you work one one or two concepts at a time, you can get those sufficiently done and move on to the next. Yes, it’s a bummer if the one of the incomplete concepts is what your coworker needs to cover a sick day, but some fully-complete documentation is generally better than a lot of woefully incomplete documentation.
- Avoid duplication. The more places the same information is recorded, the more likely it will become out of date. If documentation for something already exists, link to the authoritative source. You can provide some basic context around the link, but minimize the amount of copy/paste you do.
- Write as you learn. If you’re just getting started, try to write as much as you can as you learn it. That way, you don’t end up assuming knowledge that your reader won’t have. If you’re learning from someone else, this also gives you the opportunity to let them verify it.
Verifying
The first time you write documentation, it will almost always be incomplete. You’ll want to get feedback to help improve it. This turns out to be another benefit of small chunks with limited work in progress. It’s almost like Agile was on to something here!
- Trade places with a coworker. If you can (this requires management support for sure), swapping jobs with a coworker for a few hours gives you the opportunity to see how the documentation performs in real life. Doing it while you’re still around means that the documentation has been tested before you have a sick day or vacation. If there are problems, you can answer them without being inconvenienced.
- Get feedback quicky. Even if you don’t swap roles, at least let someone look at it as soon as you’re done writing. This way everything is fresh in your mind as the questions come up.
The mechanics
You may have noticed that I cleverly avoided discussing the technical aspects. Do you write a wiki page? A word processor document? A standalone note taking app (like CherryTree)? Rendered HTML on a docs site? I leave this as an exercise for the reader. They all have benefits and drawbacks, so whatever works best for your team is the right answer. If people can’t find or update the documentation, then why did you bother writing it?