User Experience Stack Exchange is a question and answer site for user experience researchers and experts. It only takes a minute to sign up.
Sign up to join this community
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?
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:
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.
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.
