In the rush to release your documentation, you have a lot to do. Chances are, you'll miss something. That could be a little something, or a big something. But why take that chance?
A release checklist can help you avoid making mistakes. It can help make your release process more efficient. A properly crafted checklist, whether on paper or on screen, can ensure that your documentation release goes smoothly and that you don't miss anything.
A simple list with a lot of power
Checklists should be part of any technical writer's toolkit. In his book The Checklist Manifesto, Atul Gawande writes:
... it is far from obvious that something as simple as a checklist could be of substantial help. We may admit to errors and oversights ... But we believe that our jobs are too complicated to reduce to a checklist.
The key benefit of a checklist, especially for a technical writer, is that it helps you avoid as many errors and oversights as possible.
Elements of an effective checklist
An effective checklist sounds easy to create, but it isn't. An effective checklist isn't a simple list of tasks. It's a very focused list of what you need to do. In this case, it's what you need to do to release your documentation to your users. Your checklist should contain only the information that you need and can absorb at a glance.
What should go into a release checklist? That will depend on several factors, including the number and types of documentation you're releasing, the formats you're publishing the documentation in, and how you're delivering the documentation.
For example, if you deliver your documentation on a wiki, you won't need to include items about checking the documentation into version control or generating a PDF. You will, however, want to have items on your list to check links and formatting.
You should keep your checklists as short as possible. How short? A page. Or less. The items on the list shouldn't be full sentences. Instead, write in sentence fragments—for example, Find missing punctuation or Fix broken links.
Why keep your checklist short? A shorter checklist is easier to understand and easier to read. You can see what you need to do at a glance instead of reading through two or more lines. Gawande offers a great example from the world of aviation:
Test pilots made their lists simple, brief, and to the point—short enough to fit on an index card, with step-by-step checks for takeoff, flight, and taxiing. It has the kind of stuff that pilots know how to do.
When creating your checklist, remember that it isn't a how-to. The checklist is there to remind you of what you need to do. You should already know how to carry out the tasks on the list. If not, you should learn how to do them or divide the tasks among your team.
Sample release checklist
Here's an example of a documentation release checklist that I've used in the past:
- Incorporate final technical review
- Do final editorial review
- Check spelling
- Check version numbers
- Merge all branches into master
- Build PDF manuals
- Build online help
- Spot check PDF manuals for formatting
- Spot check online help for formatting
- Check links
- Write release notes
- Write release announcement
- Publish documentation to project website
- Publish release notes
- Publish release announcement on project blog
That checklist, with a few tweaks, has served me well with about 90% of the documentation projects I've worked on.
Even when you've created a checklist, you'll need to go through several iterations to boil it down to the essentials. That means testing it over several documentation releases and working with your team to learn what worked and what didn't to learn what's needed on the list and what isn't.
Tweak the checklist with each iteration. Sometimes it might only take a couple of tries to come up with the checklist you need. Or you might need to go right back to square one.
In the end, though, you'll have a useful tool that can take some of the stress out of the rush to release your documentation.
2 Comments