Help page elements

Help pages in Ubuntu Help -- that is, those pages containing actual instructions or explanations, rather than just links to other pages -- should have the same basic elements: title, intro paragraph, redirections if necessary, procedure (for achieving goals or solving problems), conclusion if necessary, and cross-references.

Title

Titles of top-level categories should be designed for maximum scannability. Include verbs only when the nouns alone are not obvious. Examples:

• New to Ubuntu 6.10?
• Disks, folders, and files
• Software installation and management

Deeper into the hierarchy, titles may be longer, so as to address exact goals or problems. Titles for goals should be present participle verb phrases:

• Listening to music
• Sharing an Internet connection with a Windows PC
• Setting the desktop background

Titles for problems should be declarative statements (not questions), written in the first person:

• I installed a program but now I can’t find it
• The clock didn't change after I set the time
• Some keys on the keyboard print unexpected symbols

For pages that aren't about goals or problems, use whatever form is most understandable:

• If you’ve been using Ubuntu 6.06
• What is a package manager?
• How file permissions work

Intro paragraph

A page's intro paragraph should usually be one or two sentences long. It should:

• leave me in no doubt about whether I'm on the right page
• answer simple questions immediately if possible (such as which program or window I should be using)
• describe any special information or privileges I need before continuing.

Examples:

• "You can use Rhythmbox to listen to music stored on your computer or on CD. You can also copy music to an iPod or similar player, if you have one."
• "In the Time and Date window, you can set the computer’s time, date, and time zone. You can also automatically correct the computer’s clock using the Internet. You must have administrator access to do any of these things."
• "The desktop background is the picture, color, or pattern that appears behind any windows open on your screen. To change it:"

Redirections

If, when I arrive at this page, I'm likely to need another page first or instead, link to the other page(s) in a bulleted list after the intro paragraph.

Procedure

Describe the simplest and most memorable way I can achieve the goal or solve the problem. If the procedure contains more than about three sentences, use a numbered list; otherwise just use a paragraph or two.

Don't include things that aren't a necessary part of the procedure (for example, don't mention closing an instant-apply window). And don't describe the computer's expected response to any step (such as a window opening), unless it's likely to surprise me.

A single page may contain multiple procedures, if they’re very short. If they’re not, consider linking to procedures on separate pages, maybe with a sentence or two before each link to help me choose the correct one.

Conclusion

In one paragraph, describe anything I need to understand or be wary of, now that I've carried out the instructions. Also briefly describe alternative methods, or ways I can avoid the problem in future. Don't have a conclusion if there is nothing useful to add.

Cross-references

Include a bulleted list linking to closely-related topics, if any, such as those mentioned in the conclusion.

A complete example

• I installed a program but now I can’t find it If you install a program with a package manager, it should be added automatically to one of the submenus in the Applications menu. If you install a program and it doesn’t appear in the menu, you can add it yourself using the Applications Menu Editor.

  • Using a package manager

  To add a program to the Applications menu:

  1. Choose Applications → Accessories → Applications Menu Editor.

  2. Select the category where you want to put the menu item, then click “New Entry”.

  3. Choose Places → Search for Files.

  4. In the Search for Files window, choose “File System” from the “Look in folder” menu, and enter the name of the program in the “Name contains” field. (If the program’s name has more than one word, enter the most unusual word.) Press Enter to start the search.

  5. Find the program in the search results. If many results appear, scroll the list to the right until you see the “Type” column, and click the “Type” button to sort the list. Then scroll the list vertically until you find files of type “executable”, or if there are none, “shell script”. Scroll the list back to the left to find the program. (The icon for a program has a diamond in it. A file with a dot “.” in its name probably isn't the right one, but program files sometimes have names ending in “-bin”.)

  6. Return to the “Entry Editor” window for adding a menu item, and move the window so that you can also see the program in the search results. In the “Command” field, type the text from the “Folder” column for the program file, then a slash “/”, then the text from the “Name” column. For example, if a program had “honeybee” in the “Name” column and “/usr/bin” in the “Folder” column, you would type “/usr/bin/honeybee” (without quotes).
  7. In the “Name” field, enter the name of the program as you want it to appear in the menu, and click “OK”.
  If you remove the program later, you’ll need to use the Applications Menu Editor again to remove the menu item.

  • Using the Applications Menu Editor

Once you’re done, report bugs to make the help simpler

Writing helpful and reliable steps to achieve something often reveals interface design bugs. In the example above, the Applications Menu Editor should let you search for programs but doesn't, Search for Files should let you search for programs specifically but doesn't, it should be possible to sort file search results by relevance but isn't, the "Type" column should be easy to get to but isn't, the Applications Menu Editor should let you drag a program directly into it but doesn't, the dialog for adding a menu item should be titled "Add Menu Item" but isn't, the dialog should let you drag a program into it but doesn't, and choosing an icon for a menu item is so unreasonably difficult (the filepicker doesn't help) that it's not worth even including in the instructions.

So once you've finished writing a help page, report the bugs that made the help complicated, then simplify the page as each bug is fixed. As people need less help with the common cases, you'll have room to provide more help with uncommon cases, satisfying more people overall.

Comparison

• Typical components for Mac OS X help pages (bottom of page)

• Windows User Assistance road map