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
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Post History

71%
+3 −0
Q&A How I should handle gender-neutral pronouns in technical writing?

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 wh...

posted 8y ago by Monica Cellio‭  ·  edited 4y ago by Monica Cellio‭

Answer
#4: Post edited by user avatar Monica Cellio‭ · 2020-01-12T04:31:12Z (about 4 years ago)
  • 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.
  • 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.
#3: Attribution notice added by user avatar System‭ · 2019-12-08T04:49:12Z (over 4 years ago)
Source: https://writers.stackexchange.com/a/19918
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/
#2: Initial revision by (deleted user) · 2019-12-08T04:49:12Z (over 4 years ago)
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: Imported from external source by user avatar System‭ · 2015-12-01T17:19:51Z (over 8 years ago)
Original score: 3