User documentation is a tricky thing to manage. On the one hand, docs are invaluable to your clients. But on the other, keeping “Write User Manual” at the top of your priority list is next to impossible, especially as you approach your go-live date.

The secret to squeezing good user docs into your schedule is to approach them the same way you would any other deliverable: create as little as possible from scratch by building on work you’ve already done, keep your users in mind at all times, and work efficiently.

That all sounds pretty familiar, right? Let’s talk about how to adapt these practices to user documentation.

Build a Template

Every site you build is different and requires a tailored set of docs. But that doesn’t mean you should be writing documentation from scratch each time. Instead, take a few hours to pull together a docs template. Working from a template can take the documentation process from a long, painful slog at deadline-time to a set of manageable little writing sprints, spread out over the entire development process.

Where to start?

First, pull together the elements that will appear in every user manual, for example, a general introduction to Drupal. Include chapters that cover the steps in content creation, an overview of the administrative menus, and a layman’s definition of things like nodes, blocks, and views. All these chapters will remain virtually untouched, from one site to the next, saving countless hours of writing.

As you build out the framework for your docs, keep your content as modular as possible. Creating self-contained chunks does two things for you: it makes it easy to rearrange sections from one manual to the next – without extensive rewrites – plus, it helps you keep track of what content needs updating and what doesn’t.

Once you’ve got the basics covered and the overall structure of your template worked out, writing your docs will be a simple matter of filling in details. If you write up features and functionality as they are being built, by the time you’re in the deadline crunch, your docs will be 90 percent complete.

Keep Your UX in Mind

Another challenge to writing user docs is deciding how to address your readers. How technical do you need to get? What content are they going to care about the most? What tone is going to make them the most comfortable? Happily, you’ve already done the research you need to answer those questions.

Every UX discussion you’ve had about the project is going to help you determine how to slant and structure your docs. For example:

• Knowing how technical your users are will tell you how much detail you need to include. (Do you need to hold their hand through every button-click or are they CMS veterans?)
• Knowing how your users prioritize their tasks will tell you how to prioritize the content in your documentation. (Are they going to spend a lot of time shepherding content through a publishing workflow? Put your workflow chapter way up front.)
• Knowing if your users are more comfortable with formal or informal settings tells you what tone you should strike with your writing. (Do they work at a university? Coruscate, don’t attenuate. At an online surfboard retailer? Keep it bitchin’!)

As you write your docs, consult your user profiles regularly. The more you can connect with your users, the more they’ll trust your documentation and turn to it when they get into trouble.

Write as Little as Possible

One of the most daunting things about writing user docs is the idea that you have to capture every detail of this project that you’ve spent months of sleepless nights building. How are you supposed to sum up every decision you made, every feature you built, in a just a few neat and elegant pages?

The answer is: you’re not.

You’ve spent all that time, done all that incredible problem-solving, to build the awesome solutions that make the site beautiful. But here’s the thing – your readers don’t care. Your docs are not about how the site works. Your docs are about what your readers can do with the site.

To keep your docs laser-focused on your readers’ needs, you need to be able to answer one question: What’s in it for them?

Let’s say you’re writing up a section about blocks, and you spend four paragraphs explaining the ins and outs of creation and configuration. Ask: Are they going to be creating new blocks themselves? If they are, great, keep it. But if not, ditch the details. Instead give them a simple, high-level explanation of how to recognize and edit existing blocks, and move on. Keeping your manuals pared down not only saves on writing time, but also produces more useful docs.

If user documentation has been a perpetual source of frustration, these practices won’t erase all those bad memories. But if you work them into your process, you can start building new documentation experiences that will leave you – and your users – in a much happier place.

Tools for Simple Doc Writing

Process adjustments are critical for producing user docs painlessly – but a good set of tools helps too. Below are a few services and applications that can ease the burden:

• WalkHub is a Drupal-built documentation tool that lets you record interactive walk-throughs that live right on top of your site. It’s still in beta right now, but it’s coming along fast, and it provides a great way to keep walk-throughs and screenshots current, even as your site changes.
• Read The Docs is a (likely familiar) hosting platform for your documentation, which boasts features like GitHub integration, version control, and full-text search. Although the platform is slanted toward developer docs, user docs could find a nice home here, too.
• MkDocs is a tidy little tool that builds a static site for your documentation directly from Markdown files. It’s another relatively new tool in the documentation toolbelt, but if you love Markdown – and simplicity – this one’s for you.
• Pandoc – A converter that can translate your docs from your favorite markup into whatever format your clients want for their deliverables. It supports a dizzying array of languages and formats.
• And yes, there’s even Microsoft Word. Much as it might pain some of us, a lot of clients just want to end up with a nice, familiar-looking PDF that they can print out, put in a binder, and keep on their shelf. Word’s template and style functions save a lot of formatting time, and the features for automatic tables of contents, linkable cross-references, and outline-level editing make it easy to manage more complex guides.

Image: "Blindfolded Typing Competition" by wisemandarine is licensed under CC BY-SA 2.0