Take the 2-minute tour ×
User Experience Stack Exchange is a question and answer site for user experience researchers and experts. It's 100% free, no registration required.

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?

share|improve this question
    
If they're tech-savvy then why not use the actual names the controls go by in the code (Such as 'ComboBox)? That way you keep the same terminology throughout the documentation, code implementation and front-end too. –  JonW Oct 3 '13 at 13:38
2  
I'd be happy-ish using drop-down menu consistently within the documentation, but ComboBox seems clumsy and too techy - I'm not sure imposing development language words on end users is the right way to go just for the sake of consistency across all of docs, back-end, front-end, whatever? –  Roger Attrill Oct 3 '13 at 13:55
2  
What's wrong with refering to the controls by their label? "Switch on [feature] by checking/ticking/selecting [feature's checkbox label]"... In the user (!) documentation I have written, I never referred to a control by their type, but always by their "name" (label). That's how someone will find them in the UI anyway... –  Marjan Venema Oct 3 '13 at 18:14
    
@MarjanVenema Agreed. The label is enough to uniquely identify a control -- nothing wrong with saying "Check Don't show me this message again" (or "Place a check mark beside"). –  Jim Dagg Oct 3 '13 at 20:58
    
@MarjanVenema also agreed in general and where possible, but sometimes the label is very long (explanatory) or inappropriate for use as a reference. –  Roger Attrill Oct 4 '13 at 10:18

3 Answers 3

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.

share|improve this answer
1  
Yes - consistency is key and I do find it's much much harder to make references to controls when there is no suitable 'buddy' label. (unfortunately that would be out of my 'control' in this case - no pun intended!) –  Roger Attrill Oct 3 '13 at 14:26

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.

share|improve this answer
    
I'm in need for some simple terms for UI parts like combo boxes, radio buttons etc. What were your preferences for such terms? I'm rewriting a technical manual for some industrial machines where the target audience won't necessarily be computer-illiterate and won't understand those terms. For example I'm using terms like "box" or "line" for combo boxes. I guess at the end of my work I'll have to check all the alternative terms that I've used for them and then change some of them to be consistent all along the manual. –  Montag451 Apr 17 at 14:33

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

share|improve this answer

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.