7

I am responsible for developing internal IT documentation but have only begun my scratching the surface on technical documentation.

Is there a standard or best practice for the following:

Example 1: Go to File > Preferences

Example 2: Go to the Application folder

Should user actions (example 1) and destinations (example 2) be treated the same way?

A title or link to your favorite resource would be REALLY helpful.

2 Answers 2

5

The standard I found most common and probably most clear is to quote anything that appears on screen as fixed-width font on grey background. Using unicode right arrow → is the neat, elegant way to shortcut a traverse through interface.

  • Open FilePreferences and pick the Advanced tab.
  • Use the slider to adjust Allocated memory to 30MB and confirm with [OK].

(preferably, a fixed-width Serif font like Courier makes it even more clear.)

In case of any fancier icons, describe their look only if you absolutely must. Otherwise, try to use actual images. You are welcome to name them too, but the images are quite important.

  • Click enter image description here to create a new document.

You can optionally use separate markup for [buttons], [x] checkboxes ([ ] unchecked too), (o) radiobuttons, /tabs\, but it's fairly rare (outside of buttons, [OK] or [x] close button are rather common.)

Other than that, be descriptive what you try to achieve and what are the expected results, especially where given element is (use the file dialog to go to the Applications folder; pick FilePreferences from the window menu)

Use italics to describe variable content - not literal quote. Use bold to describe text that is to be typed in by the user. You can combine all typographical conventions (e.g. variable user-typed content appearing on screen).

  • The result will appear as NIC0-MAC:HW Address
  • type telnet  address port into the command window.
1
  • I agree that your "fixed-width grey background" is clear. Thanks.
    – ginag
    Oct 22, 2013 at 20:01
2

A good resource for this is:

  • the Microsoft Manual of Style (the 4th edition is available via bookstores, older versions can be found on the internet as PDF or Winhelp file).
    @SF's answer pretty much matches this style guide.

Whichever convention you end up using: document it. Add a section 'About this document' where you explain what your conventions mean.
Also, don't go overboard. A document that uses 10 different styles to indicate specific types of user interaction will just confuse the reader.
If you use a monospaced font, pretty much anything is better than Courier. I'm partial to the (open-source) Source Code Pro.

0

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.