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
1  
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
1  
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
show 4 more comments

2 Answers

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
add comment

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
add comment

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.