Writing User Guides


For the last week or so, and the next week or so, I've been working on writing a user guide for an application we launched recently. Ideally, we'd have a technical writer who would be doing this, but we're not that big a shop. Mentioning that you are writing a user guide is often met with sympathetic groans from peers due to it's relatively well-deserved bad reputation. It's tedious, it's mind-numbing, and sometimes it's necessary.

There are lots of resources on how to write a user guide, so I'm not going to do a tutorial or anything, but thought I'd share the methodology I tend to follow, which helps me survive it. 🙂

Make it Pretty
First, I deal with the template-core layout type stuff first, as much as I can. Yes, really. I'm rather anal about my documentation, even simple meeting notes, so I cannot sit and write dozens or hundreds of pages of documentation that are ugly to look at. It is also much easier to set some stuff up first versus doing it after the fact. So when I open that shiny word processing doc (Word, in my case), at the minimum:

  1. I set the page margins – generally 1" or .75" margins all around.
  2. I set normal style – font, size, paragraph spacing, line spacing, etc.
  3. I set my header styles – font, size, spacing, and colors.
  4. Set mu standard bullet style.
  5. If I am likely to have tables of settings/options, I try to go ahead and make the default table style for it (so much easier than doing them one by one!!!!)

Front Matter
For our needs, our documentation generally just has two pieces of front matter: the cover page and the table of contents.

  1. Cover page – vertically centered, with the title, et all. I'm always careful to use custom styles for all this so it doesn't get pulled into the TOC later.
  2. When I'm first starting, there isn't anything to table into a list of contents, so I throw "Table of Contents" at the top of page two, style it (again giving it it's own style so it doesn't get included in itself), and put in a section break, next page.

If we did need other front matter stuff, like a disclaimer page or something, I'd put that before or after the TOC, as appropriate.

Gotta Have Screenies
For web applications and other software, including screenshots is not really optional. Readers need a visual to go along with the text, and when many are 100+ pages, it helps break up the monotony. So I usually use Irfanview for quick screenshots that can go into the document as is. For ones that need marking up, like adding arrows, numbers, circles, etc, I use Adobe Fireworks. I always try to trim screenshots to the minimum needed to convey the feature it is highlighting, so more is visible to the reader.

Of course, while working on the user documentation, I must have a usable test/play ground version of the application for getting those screenshots. It should go without saying, but you don't play on production apps and you don't want to use "live data" for user guides if that data might include personal information! Fortunately, we have both a development and staging platform, so I generally work off our dev box with the current production copy of the code.

Plan Plan Plan Plan!
Let me say it again, plan! Being a pantser is fine when writing fiction and emails, not for technical documentation: plan it out. Remember doing those outlines in school for papers? I basically do something similar to lay out my topics. I use the various header levels to put it into a pseudo-outline form. This is where I'll sometimes look at some user guides that don't suck to bad for inspiration/ideas on content.

  1. I use Header 1 for the major functional areas, plus a first section for intro/overview stuff. For example, our application has a public end, an administrative area, and a second authenticated area for clients to pull reports. So my user guide has four major sections. In our case, this will also be doubly helpful if we want to make a second guide just for those clients: we can take this one, copy, and cut out the unneeded stuff then tweak a little. Bam, two for one!
  2. I use Header 2 for the major topic areas in each section, i.e. the main work modules/functions under the major areas.
  3. Header 3 then breaks up the work modules into specific functions/areas
  4. As needed, Headers 4 and 5 help me break those areas down even further though many of these come as I'm writing

I find it much easier to go past level 1 on the outline by having it open in one screen while I'm browsing the app in another so I don't forget any areas. As a rough guideline, anything that appears in a menu, has an actionable icon, or is linked to that is part of the application will likely have an entry in my outline. Here is a snippet showing some of this initial layout:

More Prettying
Once I have the outline, I like to go back in and do a little more "prettying" up by adding the header/footers and adding my table of contents. Depending on the depth of the application and outline, I generally have the TOC go down to the forth outline level when it's built. The main purpose is to ensure folks looking can quickly find what they need, if they are not reading it front to back.

Enough Procrastination, Start Writing!
Okay, really, one last bit of putting it off. I like to print out the TOC to use as a check list as I go along. And then it's time to just sit down and write.

As I work, I usually have the Word doc open in one window and the application open in another. I don't know about you guys, but I can't write a user guide for something I'm not looking at! As I work, I will often adjust the outlined items, especially in the Header 3 and below range to better fit the specific content I'm working on.

I also save, a lot. Like every time my fingers pause for more than two seconds, I type a period, I switch to making screenshots, I blink. Saving is my friend.

It isn't a fast process, to be sure. It takes me about 2-3 hours from the time I start working on it before I'm actually to the point of even writing the first sentences in the user guide. But the pre-set up does help me stay focused and makes the rest flow smoother. It also gives me plenty of places to do little goals – instead of the daunting "do it all", I set smaller goals of trying to have a specific section done by a certain time frame.

Most user guides for a good sized app run 100-200 pages in length, easily, with dozens, if not hundreds, of screen shots. I'm at around 75 pages as of this post and maybe 50% done. The TOC is 3 pages by itself, single spaced. I'm hoping to have it finished and ready for review by the end of the day Friday, but I'm lucky in that it's quiet around the office right now so I am able to devote 4-5 hours of my working day to it. It can easily take a month or more, when there is less time to devote to it. I think is probably the number one reason this kind of big documentation gets done so rarely, it is a time consuming and wrongly perceived as having less importance to writing code, especially if you're a developer and the one crafting such a document. 😉