Last week I spent three days in Germany for the Beyond Tellerrand Conference in Dusseldorf.

The rough translation for Tellerrand is 'edge of the plate', so the conference is all about going beyond the edge of the plate - you probably know it as thinking outside the box.

One of the talks that impressed me was from Carolyn Stransky. Carolyn spoke about documentation and how to bring a human touch into the documentation. Rather than focusing on what your product does or how it does it, explain your product through the documentation by showing users how they might accomplish the tasks that your product is designed for.

While Carolyn focused her talk on documentation, the same approach can be taken for any of the content that you are producing, especially for your careers content.

The words you use

There were a few examples of terminology you should and shouldn’t use, but these all struck a chord with me 

  • Don’t use Master/Slave, you should use Primary/Replica to describe the same thing rather than reinforce our poor treatment of humans
  • Black List / White List — does this need any clarification about how horrifically racist it is? What is worse is that it had never previously occurred to me. Instead, use Deny/Allow List.
  • Just/Simply – don’t make things sound simple because someone using your documentation will be doing so for the first time and it won’t seem like they ‘just’ need to do something ‘simple’.

One of the tools that Carolyn shared was Alex.js which parses your content through a set of rules and provides you feedback about the types of terms you should watch out for. I just copied this article and ran it through the checker and had the following results:

  1. 7:23-7:26 her may be insensitive, when referring to a person, use their, theirs, them instead
  2. 12:15-12:21 Master / Slave may be insensitive, use Primary / Replica instead
  3. 12:22-12:27 Don’t use Slave, it’s profane
  4. 13:5-13:10 Reconsider using Black, it may be profane
  5. 13:18-13:23 Reconsider using White, it may be profane
  6. 13:87-13:93 Reconsider using racist, it may be profane
  7. 14:5-14:9 Just may be insensitive, try not to use it
  8. 14:10-14:16 Simply may be insensitive, try not to use it
  9. 16:178-16:182 just may be insensitive, try not to use it
  10. 21:15-21:21 simply may be insensitive, try not to use it
  11. 26:49-26:52 her may be insensitive, when referring to a person, use their, theirs, them instead

Other tools that were recommended included 

Check out Carolyn’s website, and take a look at her video linked.