User Experience Stack Exchange is a question and answer site for user experience researchers and experts. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

I have a fairly large CRM-type Sass application for which I writing the help section. I'm wondering how should the help be best written:

1) When you press the blue button, you will do something cool

2) Pressing the blue button does something cool

In the first case, the software talks to the person. In the second case, the sentence is impersonal.

What's better and are there other options?

share|improve this question
slightly off topic, but this link is interesting for anyone involved in creating help documentation: - the conclusion in particular – Toni Leigh Aug 5 '13 at 17:58
up vote 2 down vote accepted

You should structure an action descriptive text to start with the effect of initiating the action. With your example above it would in that case be:

  • Do something cool by pressing the blue button

The reason behind this is that the user will scan a list of action looking for the desired effect, the interactive pattern ("press the blue button") which doesn't really say anything about the action is secondary information and should therefore be ordered last in the text. This way it's easier to find the desired action.

Regarding your initial question, whether it should be formulated as speaking to the person or just describing the action I would suggest that you stick to describing the action period. This way the descriptions can be cut shorter and more concise, and you're able to say more using less space/text.

share|improve this answer

I would say there is no need to write a manual. It is highly likely nobody will read it. TL;DR epidemic is here and progressing.

Usually I suggest to simplify form structure, to split text into smaller chunks and let user access that help right from the application.

enter image description here

Tooltip or some special dialogue can be used to show a small chunk related to some particular component.

If you need more space to explain some complex concept, for example, you can use something like insets. Pay attention to the help block, it appears after pressing blue icon.

enter image description here

share|improve this answer
I should have added in the question that I wasn't talking about writing a manual but rather a popup that explains how the page works. I already have several tooltips already. – frenchie Aug 5 '13 at 16:02

Your Answer


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.