: Standards for representing user interaction I am responsible for developing internal IT documentation but have only begun my scratching the surface on technical documentation. Is there a standard

Vote Up Vote Down

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)

Vote Up Vote Down

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 File → Preferences 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 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 File → Preferences 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.

(0)