Take the 2-minute tour ×
Writers Stack Exchange is a question and answer site for authors, editors, reviewers, professional writers, and aspiring writers. It's 100% free, no registration required.

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.

share|improve this question

2 Answers 2

up vote 3 down vote accepted

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.
share|improve this answer
    
I agree that your "fixed-width grey background" is clear. Thanks. –  ginag Oct 22 '13 at 20:01

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.

share|improve this answer
    
Thank you for the resource. –  ginag Oct 22 '13 at 20:03

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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