0

I'm wondering about the correct way to mark up icon/menu item/dialog names in the context of technical writing (user's guide). Here's a small excerpt from a document I'm writing:

Clicking the “Duplicate Register Map” icon creates creates a deep copy of the corresponding register map. The copy gets the same name as the original register map with the addition of a - COPY suffix. Please rename the copy using the Edit Register Map dialog afterwards to give it a valid name.

Is it better to use quotes or italics for such purposes?

2 Answers 2

1

It depends on the publishing platform, your writing tools, and established conventions. As mentioned in the previous answer, commands and button names are often highlighted using bold type. But if the text might be spoken, or read in something that doesn't support formatting (Notepad, for example), then typography doesn't work as a distinguishing sign.

Similarly, if you start bolding UI elements in instructional text, you can end up with text that's hard to read because it's littered with bold, like a black-and-white checkered floor.

I avoid quotes to identify regular commands and menu items. Instructional text can become littered with quote marks. Instead, I reserve quotes for long titles of options and other UI elements, like this:

Select the "Don't save on exit" option, and then click Save.

You can find style guides produced by Apple and Microsoft. Both provide abundant advice about labels for UI elements, typography, procedural language, and other concerns of technical writing.

Trivia: For years, Apple called one type of interface element a "radio button" while Microsoft called the same thing an "option button." One required you to write "check box" (two words) and the other used "checkbox" (one word). I used to have all of this memorized, and then mobile interfaces and the Web happened, and things become less formal.

The important point is to be consistent. In most cases, you should also provide a "key to typographic conventions" in the documentation, where you explain the use of bold, italic, and other typographic or language conventions. Look at any long manual for an example of this.

2

It doesn't really matter as long as you're consistent. In some domains, there are established practices (Windows menu names are generally printed in boldface and submenu items are indicated with |, e.g., File|Save (fancier still is to underline the shortcut letter)¹, while on MacOS there is no typographical distinction for the menu names and submenu items are indicated with > (note spaces), e.g., File > Save). So I would check for generally used practices for your platform as a guideline but otherwise, it's enough to be consistent in your style.


  1. This may have changed—the last time I used Windows regularly was a while ago and it's been even longer since I documented Windows software.
1
  • Thanks for the advice.
    – geschema
    Aug 8, 2021 at 8:33

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.