ITS Style Guide

Writing Procedures

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. Use the guidelines and tips provided here to write good, concise procedures. For examples of this practice, please see the procedures on the Premium UT (Exchange) E-mail Web pages.

If you need help writing procedures for ITS-related services, contact ITS Strategic Communications. We have professional writers who can help you.

Guidelines

Tips

Guidelines

1. 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 query on. Compare these two titles for the same procedure:
   • Setting Up an Outlook XP Profile
   • Setting Up Outlook 2003 to Access AEMS E-mail and Calendar
2. 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.
3. List any prerequisites or dependencies before you begin the procedural steps.
4. 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.
   
   http://server-address/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. If you are producing print only, you may use lowercase and boldface.
   
   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.
5. 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.
6. At the end of the procedural steps, tell readers where they can find more information, if it is available.
7. 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.

Tips

• Give readers the essential information first. Essential information is that which helps them complete the procedure.
• 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.
• If you are writing a procedure for a task in Internet Explorer that requires a menu command, place the following text in a note preceding the first step or at the end of the step requiring the menu command:
  
  If you are using Internet Explorer 7, press ALT to display the menu bar. You can display the menus permanently by clicking the Tools button and selecting Menu Bar.