Having inclusive names in docs examples

#discuss #inclusion #docs

We want to make the names we use in our docs examples more inclusive from both a gender and a cultural perspective.

We use a docs-as-code approach to docs so we're interested in automation and scalable approaches.

Is this something you or your team have worked on?
Could you recommend any best practices in approaching this?

Thank you!

Top comments (1)

We've been discussing a couple of approaches within the team.

First, we could have a list of names to choose from manually as we write the docs. Potential issues with this approach are that:

there is cognitive overhead in choosing, writing, and remembering the name as we produce the content
some names will inevitably be chosen more often than others
manual steps are error-prone

Second, we could have a way to randomly generate names. This approach would mean that:

the writer only needs to remember, for example, the function to randomly insert a name
we can ensure consistency within a page or section
there is an equal chance any name gets picked since the selection is random