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?


2 Answers 2


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.


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

  • 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
    Commented Aug 5, 2013 at 16:02

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.