Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs

Dashboard
Notifications
Mark all as read
Q&A

How I should handle gender-neutral pronouns in technical writing?

+3
−0

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.

Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/19910. It is licensed under CC BY-SA 3.0.

0 comment threads

3 answers

+3
−0

Using "he/she" 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.

Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+1
−0

I would write around it this way:

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

Sounds awkward to me. Presuming POS means "Point of Sale" and not "Piece of ..." okay it can't mean that. Is "checkin" "Check in"? Whatever.

Rewrite: When the user requests that a visit and order be registered in their account, a checkin is created at the POS.

Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+1
−0

I will cheerfully use "singular they" if that is a particular person's pronoun, but not as a lazy substitute for "he/she."

Rewrite the sentence, either as plural or as second-person.

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

2) When you request for your visit and order to be registered in your account, a checkin is created at POS.

Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »

This community is part of the Codidact network. We have other communities too — take a look!

You can also join us in chat!

Want to advertise this community? Use our templates!

Like what we're doing? Support us! Donate