DEV Community

loading...

Having inclusive names in docs examples

bravegrape profile image bravegrape ・1 min read

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!

Discussion (1)

pic
Editor guide
Collapse
bravegrape profile image
bravegrape Author

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