ITS Style Guide
Writing procedural documentation
This document describes Information Technology Services (ITS) best practices for effectively writing procedures involving steps and instructions. Procedures should comply with ITS Style Guide standards. For procedures on the ITS Web site, you should conform with Accessibility Guidelines.
For an example of good procedural documentation, please see the Austin Exchange Messaging Service Web pages.
- Give readers the essential information - information that will help them complete the procedure - first.
- Limit the use of screen captures.
- Make the steps as brief as possible.
- Write in present tense.
- Keep procedures as short as possible. If a procedure becomes extremely long, see whether you can logically break it up into two shorter procedures.
- Reduce the number of decisions a reader has to make. If necessary, move some decision points outside the process steps or redesign the software interface for more consistency across platforms.
- State conditionals ("If you are using a Macintosh…") clearly at the beginning of sentences or paragraphs, so that readers can skip text that isn't relevant to them.
- The first word of the procedure title should usually be the gerund
form of a verb (for example: configuring, setting, etc.). Make sure
the title uses terms the user will understand and search on. Compare
these two titles for the same procedure:
- Setting Up an Outlook XP Profile
- Setting Up Outlook 2003 to Access AEMS Email and Calendar
- Describe what the procedure will accomplish in terms that the audience
will understand. Do not simply repeat the same words from the procedure
title. Compare these two explanations:
- This procedure describes how to create a profile in Outlook 2003.
- The Outlook 2003 program provides access to your e-mail and calendar on the Austin Exchange Messaging Service (AEMS) through the creation of a “profile.” Defining a profile tells Outlook how to locate and log into your mailbox on the server. (This procedure is similar to defining an e-mail account in other e-mail programs.) This document describes the procedure for setting up an Outlook 2003 profile on your Windows XP or Windows 2000 machine.
- List any prerequisites or dependencies before you begin the procedural steps.
- Use boldface to highlight names of menus or buttons,
use italics for items that will be replaced with user text,
and set off the text that the user should insert with either quotation
marks or an indented line. Example:
From the File menu, select Open. In the Open text box, enter the URL below, substituting either “disk.dallas.utexas.edu” or “disk.houston.utexas.edu” for server-address, and your UT EID for eid.
When prompted for your user name, enter it in the form “dallas\eid” or “houston\eid” and enter your password at the prompt.
Avoid using characters such as angle brackets (<>) or square brackets ([ ]) to designate text substitutions. Readers frequently enter these characters as part of their text.
Except for Unix documents, references to a language statement or system command should be in uppercase for online documents: for example, EDIT command, DIRECTORY command, IF statement.
For Unix documents, commands must be shown in lowercase, but use boldface, if possible. For example:
To use Bash on a Unix system, type bash at the prompt.
Be sure readers can distinguish between commands to an operating system and commands to a program or processor. In some cases, you may be able to use the word "directive" or "statement" for internal commands in order to avoid confusion between the two. Or you can use expressions such as at the Windows> prompt or at the prompt from Pine.
- Supplement text descriptions with screen captures or graphics if necessary, but don't overdo it. For accessibility reasons, don't use a graphic instead of a text description.
- At the end of the procedural steps, tell readers where they can find more information, if it is available.
- Move background or extensive discussion of conceptual or technical details to a reference section at the end of the document, or link to another page where complete background information can be provided.