1

I am writing API documentation for a mobile loyalty program and I am not sure which of the following is better wording:

1) When the user requests for their visit and order to be registered in their account, a checkin is created at POS.

2) When the user requests for his/her visit and order to be registered in his/her account, a checkin is created at POS.

Which sentence is correct and why? If neither is correct, please show me the correct way and explain why. Here, 'user', is any person in general public who goes to a Point Of Sale Terminal.

3

Using "he/his" will annoy some of your readers; using singular "they" will annoy others. And referring to a user as "it" will seem weird to most people.

What I do is to write around the problem wherever possible. First off, if you're referring to the user of your API, it's better to write in second person imperative anyway -- "do this, then do that". It's clear, direct, and less convoluted than "descriptive" style ("the user does X and...").

Maybe you're not talking about the reader, though -- your reader is building something (using your API) that will in turn have users, and you need to talk about those users. For example, let's talk about an API that lets your user build an app that somebody else will log into and configure. Here are some examples of ways to talk about that user without using gendered or wrong-number pronouns:

The user creates an account and registers it with your service.

After logging in the user can access a configuration menu to (do something).

I had to work a little to come up with those examples, not because of the writing style but because most of the time your API documentation shouldn't be talking about how your reader's users do something. After all, your reader is responsible for the user interface. You're more likely to write things like this:

When the user logs out, remember to call some_function() to also flush the session data.

Use the register() function to tie a user ID to an OpenID credential.

1

Your second and third options ("his/her" and "their") are both fine.

The choice between them is a matter of taste. Strictly speaking, the use of "singular they" is ungrammatical, being a plural pronoun used to describe a single person, but it has a long history as a colloquialism and is becoming widely used as a way to avoid making assumptions about the gender of the person being described. "His/her" is more grammatically acceptable but clumsy and doesn't transfer well to speech. You could also use "his or her", which is unquestionably correct in grammar but takes a long time to write or say.

Don't use the first option ("its"), as the use of "it" implies that the user of your loyalty program is not human. Perhaps in the future we will need to find ways to allow for the possibility of users who are robots or genderless beings from other planets, but that time is not yet.

  • The use of 'singular they' predates criticism of its use by several centuries, it's only considered ungrammatical by the same kind of people who make up arbitrary rules about split infinitives and get upset by people using the word 'literally' for emphasis. If it's good enough for William Shakespeare, it's good enough for your technical documentation... – evilsoup Dec 1 '15 at 22:32
  • 1
    William Shakespeare and O'Reilly Press probably follow different style guides, though. You have to follow the norms of your context, whatever they are. – Monica Cellio Dec 1 '15 at 23:23

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