How to design and write a technical reference guide
Technical reference guides are common in many tech industries, but they’re not appropriate for all tech products. If you’re new to technical writing, how do you know if you need a reference guide, how do you design topics in a reference guide, and how do you write clear information?
What is a reference guide?
But first, let’s define exactly what a reference guide actually is. It’s a technical document that steps through the interface of hardware or software in a methodical way. For a hardware product, it will usually go through and describe each button and feature from left to right, and front to back. For software, the manual is organized by menus and menu options and describes every single feature in the product.
Unlike a user guide, which provides step by step instructions on how to work through sometimes complex processes involving a lot of different commands and features, a reference guide is just that—reference. If you want to know what a button on some hardware is for, or what a toggle in a software dialog box does, a reference guide will explain it. What it won’t do is explain workflows.
When should you develop a reference guide?
Not all products benefit from a reference guide. Let’s consider a software product all of us probably use sometimes: Microsoft Word. When you look at the documentation for Word, you’ll find easy to follow steps for completing workflows (which is user guide information). Examples are How to print a document, How to set up multilevel lists, and so on. If you open the online help for a dialog box (click on the ? button), you’ll find information on how to complete different tasks instead of explaining what each item in the dialog box is for. A reference guide for software like Word wouldn’t be terribly useful for people trying to figure out how to do different things.
Reference guides are mostly useful for complicated hardware with so many different options that users sometimes want to look up what a certain button or option is actually for, and maybe what the rules are for entering information. Note that I said “complex.” If you’re documenting some fairly simple hardware, like a home modem, a reference guide would be overkill.
How do you structure a reference guide?
Since reference guides don’t document workflows, they are usually set up to follow the interface of whatever you’re documenting. So as mentioned earlier, start on the front left of hardware, then work your way to the right. Describe every button or widget, including any features that are available when you push the buttons. When you’re done with the front, move on to the back. For software, start with the menu option on the left, describe every option under that menu, and work your way to the right.
What should reference guide topics include?
In-depth description of what it is and what it’s used for
Reference guide topics should include an in-depth description of each option. People who are looking up reference information often want some of the technical details to better understand each feature. This is where digging into design specifications comes in handy. If there aren’t design specs, or the specs suck, that’s when you need to talk to developers to find out exactly what the option is for. Think of questions like this:
What is the technical reason this option exists?
What will users do with it?
How will using this feature benefit users and improve the workflow?
What do users need to do before using this particular feature?
Illustration or screenshot
You should include an illustration or a screenshot of the option you’re describing. This helps users make sure they’re looking at the correct topic. You can also use captions and arrows to point to different things in the illustration to describe anything unusual.
How to find it and configure it
After you have a general background for the option as a whole, then you need to tell people how to actually find it. For hardware, include a photo or illustration of where the button is located. You can just include a photo of the hardware, and use a graphics program to put a circle or rectangle around each option as you describe it. For software, include the menu path to the option (something like File > New > Add New Gidget is a common way to include menu paths). If there’s an icon in the software, include a screenshot of it. Also include anything specific people need to do access it. Like if you have to click on something before you can activate a command, include those instructions.
Describe every option
Next, you need to list every option and feature that’s available. Let’s take a look at an example. I don’t have any complex hardware at my house I can use as an example, so let’s take a look at this dialog box in Microsoft Word.
First, you’d start with what a cross-reference is, why you’d want to use it, and any technical details about how it works in the program (like cross-references are actually fields, which is a technical topic that would interest some users).
Then, you’d go through and describe each option.
Insert as hyperlink:
Separate numbers with
For which heading:
Insert reference to:
The idea here is that if someone is using this dialog box and wonders “What is the Separate numbers with option for and what kind of information can I enter there?” the reference information will answer that question.
You’d write clear and complete instructions for each of these. You’d also need to explain all of the options that are available from the two pulldown lists (Reference type and Insert reference to). If the dialog box changes significantly if you choose different options, it’s a good idea to include a new screenshot or illustration and describe each option the users see.
Another helpful thing to include in reference guide topics that not all writers include but I find not only helpful but essential, is prerequisites.
Prerequisites tell readers what else they have to do before using this specific command. It’s most help to include this at the top of each section so it’s obvious what you have to do first. For example, for the cross reference box described above, you have to create headings or numbered items before you can create a cross reference. So tell people what they have to do first. If you also develop a user guide for the product (some applications have both a reference and user guide), you can also include cross references to sections in the user guide that are related.
I can’t describe how irritated I get at a certain graphics program that shall remain nameless when I try to look up how to do something in their online help. Often I find the command I need to use in the online help, but when I try to actually use it in the software, it’s grayed out and I don’t know why. Just include a section in your topic writeup called Prerequisites or Before Using this Command or whatever you want. Then, just list the things that need to happen first and include a cross reference to the topic so the person can read more. For example:
Before using this command:
Before inserting a cross reference, you must create at least one of the following:
This is a simplistic example, but hope you get the idea.
Here’s a photo of one the first reference guides I ever worked on. Yes, it was delivered in print (yikes). This software isn’t sold anymore so I can share a photo of it. You can see this basic structure: Overview of what it is, how to access this command, a screenshot of the dialog box, and descriptions of all the options.
How should reference guides be delivered?
When I first started my career, we produced printed reference guides. They were gigantic. The photo above is from a reference guide that is over 650 pages long, and it’s just volume 1! That format is obviously obsolete now not just because it’s hard to find what you need in a print book, but also because it’s too expensive now to print giant books like that. The best way to deliver reference guides is in some sort of easily searchable format, like on a website or in PDF format for easy access. If people have a burning desire to have a print book to write in, they can print the PDF. Online help files also sometimes contain reference information.
Reference guide examples
Oracle is a complex database management product. Here’s one of their reference guides.
AutoCAD is engineering drafting software. It has a ton of documentation that you can look at. Here’s a reference guide for customizing settings in the software.
SAP is a business management software system that I used in passing a few years ago and it’s incredibly complicated. They have a PDF reference guide that you can study.
Cisco makes complicated telecommunications hardware and software. They have a bunch of reference guides and other documentation on their website. Here’s an example.
I worked at Adtran for a number of years and worked on this reference guide. It’s similar to the Cisco document, but much longer. When I worked on it, it was up to 900 pages if you were to print the whole thing. You have to sign up for an account, but there’s also a huge documentation library you can check out. Adtran’s documentation is high quality so it’s a good resources to study.
What else do you want to know?
That was a good overview of reference guides. Do you have any questions? Just post them below!