What is the correct way to reference GUI controls when writing content and copy

Question

I'm writing documentation. It's technical documentation and my audience should be tech-savvy.

However, I have reservations about referring to UI elements in an interface by the terminology that developers will know and use day to day.

E.g. a dialog may contain a number of combo boxes, radio buttons, and check boxes. But different people may use drop-down lists, option buttons and tick boxes.

The distinction between an editable combo box and a non editable drop down list is not one that I want to matter in the documentation.

Yes, the docs are for the tech savvy but that doesn't mean I don't want to make the copy as digestible as possible for all readers.

So for example:

...change where you edit code by choosing the editor in the [drop-down list / combo box / menu thingy]

...switch on the [feature] by [selecting / ticking / checking / enabling] the [checkbox, tick box, option thingy]

My instinct is to vary different phraseology to avoid needing to reference the name of the controls in this way at all:

...adjust the [some label] option to change the editor used to view source code

...tick the [some label] option to...

.. (de)select [name] and you're done.

What other options are open to me, to make reading documentation better and more enjoyable for my users when referencing ui controls?

Answer 1

Revisiting this question and having resolved my problems I see that there were two issues preventing an accepted answer.

Firstly, the fault was mine - I don't think I formed the question well. I was asking something too specific whereas really I should have been taking a step back and looking at the documentation style as a whole. I shouldn't have asked what to call the controls, so much as how to write in a readable way whilst referencing ui controls.

Secondly, (and as a result of the first problem), I don't believe there was one single answer that was going to cover everything I wanted.

My problems were resolved by a number of steps, not just by a single change.

• I referenced ui controls by their buddy label where possible. That much was clear from the outset.

• Terms like button, list, text, drop-down list, checkbox and option were used consistently but only where I had to. I kept the terms simple and avoided things like radio button, radio group, combo box, select box, text field.

• I ensured that use of any such terms, like those above, were not used repetitively. In fact I actively tried to avoid using the word button if possible. When I was finished I search for all occurrences of the ui terms and considered alternative (better!) ways to remove the term. There were usually better options which came to mind more easily on re-reading the text at a later date.

• Long labels that referenced a ui component used an ellipsis at a suitable point. In these cases I provided just enough of the label for the reader to recognize and easily distinguish the control.

• I consistently emboldened the labels to encapsulate them as a 'thing'. This helped to highlight direct references to controls and also helped to inject the label into the flow of a sentence without confusing the words of the label with the words of the surrounding sentence. I also made sure that I reserved use of bold text only for references to ui components!

• I tried to give an easily readable associated action and consequence to take focus away from the control itself.

• For iconic buttons that had no associated text, I embedded the icons (rather than labels) into the flow of the text.

• I was consistent about the names given to larger containers of ui elements. I called out these containers early on in a topic so that it could be referred to later.

• Last but not least, I set out right at the beginning what the notation and format was throughout the documentation. This sets expectations of what follows and also lays out the ground rules for me as a writer and for the readers. I found as I went that I added a few rules that simplified things and reduced some repetitive aspects of documentation, and I then revisited previous writing accordingly.

For the purpose of technical documentation and simplifying technology in a very readable way, I researched the work of David Pogue and his missing manuals.

For writing readable content in any situation I took a lot of inspiration from Ginny Redish's 'Letting Go of The Words' (Amazon).

---

_{If anyone wants examples of technical writing based on using these principles, feel free to contact me directly.}

Answer 2

I generally use the following terms for form elements:

• Field
• Select Box
• Checkbox
• Radio Button
• File Upload Button

The important thing, no matter what term you use, however, is to reference the element by its corresponding label to provide enough context to the user to figure out what you mean. For example, "Check the "I agree to terms" checkbox."

The next most important thing is to be consistent.

Answer 3

Standard GUI controls such as forms are fairly has fairly standardized names. You could start from looking at the glossary over at the User experience guidelines for Windows 7 as a reference: http://msdn.microsoft.com/library/windows/desktop/aa511441

For describing common design patterns I would recommend you to look at: http://welie.com/patterns/index.php as a reference.

If the system you are trying to describe includes unique patterns and components try to come up with own labels that are easy to remember. Think about how Apple is talking about product features (like Time Machine, Scoped search etc). Easy to remember and you feel a little like Steve Jobs.

And finally I would recommend you to give the components and the variations of the components unique IDs. Let's say you want to talk about the top navigation bar in the header. And you want to talk about how it should behave when someone has opened it and you have created two variations of how the menu looks like when it's opened.

Start by giving all the main page areas (such as the header, sidebar and the footer a abbreviation (for example hd: header, sb: sidebar, ft: footer.) Then you give the top menu (and all other menus on the site the abbreviation .m, then the opened version of the menu .01 and the two variations v1 and v2. So, you end up with hd.m.01.v1 and hd.m.01.v2.

No, this will not win the Nobel Prize in Literature but it will be very easy to use this ID structure when you want to reference a wireframe documentation, a photoshop comp och live code. You can store all these IDs in an excel file or as a Table of content page in your documentation.

For more information about labeling, components and IDs I would recommend the book Modular web design: Creating Reusable Components for User Experience Design and Documentation by Nathan Curtis - http://www.amazon.com/Modular-Web-Design-Components-Documentation/dp/0321601351