Addressing End-Users (specifically Laymen)

[neelcm]

While writing Help Guides (User Guides, Online Help) what should be used?

1. To address User, one should use (S/He) or neutral (you/user/end-users)
2. Passive Voice/Active Voice
3. Present Tense/Mixed Tense (Past + Present + Future)
4. There are many sentences that dont make sense writing in active voice. So, is it fine if we use mixed voice structure to explain our points in writing.


Looking for answers to these small queries which bother me while writing s/w documents.

Regards, Neelima

[Maeve]

While writing Help Guides (User Guides, Online Help) what should be used?

1. To address User, one should use (S/He) or neutral (you/user/end-users)
2. Passive Voice/Active Voice
3. Present Tense/Mixed Tense (Past + Present + Future)
4. There are many sentences that dont make sense writing in active voice. So, is it fine if we use mixed voice structure to explain our points in writing.


1. I'd say "you" or "end-users"; Either avoids the he/she quandary.

2. There's nothing wrong with passive voice. Careful writers scrutinize their use of passive voice to be sure there isn't a livelier way to express the same thought. Too much passive voice makes for dull, imprecise writing. BUT passive voice is your friend in some situations--like yours.

3. Writing a guide is rather like writing about literature. Present tense is the preferred tense. You may have an occasional use for past if you're describing something in the past, something outside your instructions.

Ex. While the earliest light bulbs lasted only a few days, your lightbulb will last a million hours.

4. This seems to be the same question as No. 2.

[Cecily]

I've been a technical author for 20 years.

1. I use "you" wherever possible, not because of he/she/they issues but because you get simpler sentences, making instructions easier to follow.

2. There is nothing inherently wrong with the passive voice. However, for user guides etc, active instructions are clearer; I reserve the passive for things such as "The logon screen appears".

3. I don't consciously analyse my tenses, but most of what I write is in the present tense.

4. See #2.

[Maeve]

I've been a technical author for 20 years.

1. I use "you" wherever possible, not because of he/she/they issues but because you get simpler sentences, making instructions easier to follow.

2. There is nothing inherently wrong with the passive voice. However, for user guides etc, active instructions are clearer; I reserve the passive for things such as "The logon screen appears".

3. I don't consciously analyse my tenses, but most of what I write is in the present tense.

4. See #2.

I agree that "you" is often simpler and it is idiomatic. However, I try to avoid it in writing.

And I agree that passive voice has its uses. However, in your example, "The logon screen appears," the verb is in the active voice.

Present tense is popping up in much recent fiction. I find it distracting when used for narrative.

[Maeve]

I just noticed the title of this thread.

The plural of layman is laymen.


lay: not in holy orders. In a monastery there are monks who pray and do intellectual work, and those who do manual work and attend to secular affairs. The latter are called lay brothers. The term has spread to non-religious professions. Someone who lacks professional knowledge of a particular profession is called a layman. In a church setting one may speak of the clergy and the laity (non-clerical members of the church).

[Cecily]

I agree that "you" is often simpler and it is idiomatic. However, I try to avoid it in writing.

Surely it depends what you are writing and who it's for. In this specific context of user guides etc, I think it is almost always the best option; however, I use it much less in other contexts.


And I agree that passive voice has its uses. However, in your example, "The logon screen appears," the verb is in the active voice.

Oops, so it is. More haste less speed.