Writing technical documentation: How to refer to a 'user'

Question

Hi. I really don't know any better place than here to ask this, so here I go.

I am writing techincal documentation for a small college project. A big question is, how to refer to a 'user'. I don't want to refer to it as a male since I will be targetting female students and it would seem unfair.

Is it ok to call a user - 'it'

Like:

Asking 'it' to install the software. Asking 'him' to install the software. Asking 'her' to install the software.

Please forgive me, English is not my first language however this has to be done in English.

I asked here because many of you might have written techincal documentation.

Answer 1

No, it is not acceptable, either as good English or as a polite way of addressing someone. I suggest "you", or if you feel you must be more passive "him" or "her" consistently, or possibly "the user".

Answer 2

Although you don't want to overuse this, you can just say "the user"

For example:

"Asking the user to install the software."

However, you don't want to use this more than a few times in a paragraph... otherwise it gets frustrating to read in English.

Generally "he/him" is gender-neutral, however if you're targetting females, there's nothing wrong with using "she/her"

Do NOT use "it"!!!

You can always write a footnote explaining why you're using female pronouns.

I was reading an article on stuttering and there was a footnote on he* which said: "In this article, we will use the male pronoun, as 90% of those who stutter are male. You could do the same.

In addition to all of this, you can also write in an indirect style to minimize this completely.

Answer 3

Don't write many user guides, but we use user stories and personas a lot in requirements gathering.

I'd refer to the user by the role you are portraying, for example Student. It is also not uncommon to say (s)he or something like that.

Answer 4

What is wrong with just using "user?" i.e. "Asking the user to install the software." It's a perfectly valid construction.

Answer 5

For general documentation, writing 'the user' often works. For example "Asking the user to install the software." Nothing wrong with that. User is not a gender specific term so it works well.

However, you mention you are targeting female students with this project. Based on that, using feminine terms throughout makes sense.

Answer 6

Reading About Face 3 by Alan Cooper, I was pleased to notice that he says "her" each time he has to refer to a user of a software product or a device. I would suggest doing so.

"To ship an order, she has to click on the button below"

Now, you can also refer to a user by the word "user" or similar words, without using he/she. To avoid repetition, try to find other words like "person", "human", etc.

"First, the visitor has to add at least one product to a cart. If the cart is empty, the "Ship order" button will be disabled. The person can add up to 1000 products. Note that the customer can terminate or cancel the order at any moment."

Be careful. The reader of the documentation must understand that you are talking about the same actor each time. Reading requirements, I am often confused between the terms of customer, client, visitor and user. Frequently, the writers of those requirements assume that the visitor and user are people who use the website, but customer or client is the person who ordered the website to our company.

If you use UML, you can also refer to the user by a label given to a user in UML actor diagram (would it be "Student" in your case?).

Answer 7

I found this article the other day when struggling with the exact same problem. If English isn't your first language it may be a hard read because it refers to a few grammatical structures that can be complicated. The solution that I decided to use was to use "s/he" and "him/her". It shows your reader that you are explicitly considering your use of pronouns and can deter criticism if that is what you are worried about. As an added benefit it can add length to your document if it is for a school assignment!

Answer 8

The term user is universal enough today that it is a fine idea to use it. There's actually books on this stuff.

Read: "The User Manual Manual" by Michael Bremer