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:
- 7:23-7:26 her may be insensitive, when referring to a person, use their, theirs, them instead
- 12:15-12:21 Master / Slave may be insensitive, use Primary / Replica instead
- 12:22-12:27 Don’t use Slave, it’s profane
- 13:5-13:10 Reconsider using Black, it may be profane
- 13:18-13:23 Reconsider using White, it may be profane
- 13:87-13:93 Reconsider using racist, it may be profane
- 14:5-14:9 Just may be insensitive, try not to use it
- 14:10-14:16 Simply may be insensitive, try not to use it
- 16:178-16:182 just may be insensitive, try not to use it
- 21:15-21:21 simply may be insensitive, try not to use it
- 26:49-26:52 her may be insensitive, when referring to a person, use their, theirs, them instead
Other tools that were recommended included
- https://github.com/btford/write-good – similar to Grammarly or Hemmingway App but for your text editor
- Don’t say simply – https://www.youtube.com/watch?v=1vvjiJFsT-Y&t=2367s
- Mark Down Cheat Sheet – https://bit.ly/md-cheatsheet
Check out Carolyn’s website, and take a look at her video linked.
It’s no secret that most people don’t read technical documentation for pleasure. Users often come to your docs when they are frustrated with your software, disappointed that they haven't been able to solve the problem on their own and generally feeling pretty low. This is sad, sure, but being aware of these feelings is key for developers and technical writers alike. These emotions frame the reader’s perspective and therefore, should shape the mood of our docs.