4 ms·

How to remove condescending language from documentation

3 points by Kye 7y ago

Kye 7y ago
Abstract: >> "With documentation, it's rare for terms like easy to be intentionally condescending. Often times, writers use them to show that something isn't as intimidating as it sounds. If this is the case, think about what the docs are trying to communicate and replace the condescending language with word choices that better represent the intention."
herendin2 7y ago
In any learning situation, this type of language can be deeply demoralizing, because it makes struggling students feel that their teacher is totally unable to understand them and their challenges. Sometimes they may even be right about that!
- Kye 7y ago
  I hit this wall hard with every math teacher. The world seems to be divided into three groups: people who get math easily, people who got math with some effort, and people who can't get the other two groups to slow down and let everyone else process their explanations. Math teacher, with a solution 60 steps in: "See? Simple!" Me, having been unable to break them out of the zone for the last five minutes: "Okay so back on step 1 you said..." Fortunately YouTube came about just as I hit college remedial classes, and some of the math channel people seem to get it. Plus, I can make them stop with the pause button while I process something.
  - mytailorisrich 7y ago
    There is a difference between being condescending, i.e. patronizing superiority, and an expectation of a certain level of expertise/understanding of the topic under discussion. Sometimes lecturers assume students are more knowledgeable than they actually are (rightly or wrongly).
    - Kye 7y ago
      Sometimes there is patronizing superiority. I've been called an idiot for not getting someone's explanation in various subjects. I never know what kind of person they'll turn out to be until I ask for more details. The article offers some handy tools and tips to avoid being Schrodinger's Asshole in writing documentation.
Bella-Xiang 7y ago
The condescending language indeed makes people uncomfortable, especially for the newbie of this field. Funny experience and a good guide that encourages me in doing the same thing as the author: remove the condescending language from various documentation.

3 points by Kye 7y ago

Kye 7y ago

Abstract: >> "With documentation, it's rare for terms like easy to be intentionally condescending. Often times, writers use them to show that something isn't as intimidating as it sounds. If this is the case, think about what the docs are trying to communicate and replace the condescending language with word choices that better represent the intention."

herendin2 7y ago

In any learning situation, this type of language can be deeply demoralizing, because it makes struggling students feel that their teacher is totally unable to understand them and their challenges. Sometimes they may even be right about that!

Kye 7y ago
I hit this wall hard with every math teacher. The world seems to be divided into three groups: people who get math easily, people who got math with some effort, and people who can't get the other two groups to slow down and let everyone else process their explanations. Math teacher, with a solution 60 steps in: "See? Simple!" Me, having been unable to break them out of the zone for the last five minutes: "Okay so back on step 1 you said..." Fortunately YouTube came about just as I hit college remedial classes, and some of the math channel people seem to get it. Plus, I can make them stop with the pause button while I process something.
- mytailorisrich 7y ago
  There is a difference between being condescending, i.e. patronizing superiority, and an expectation of a certain level of expertise/understanding of the topic under discussion. Sometimes lecturers assume students are more knowledgeable than they actually are (rightly or wrongly).
  - Kye 7y ago
    Sometimes there is patronizing superiority. I've been called an idiot for not getting someone's explanation in various subjects. I never know what kind of person they'll turn out to be until I ask for more details. The article offers some handy tools and tips to avoid being Schrodinger's Asshole in writing documentation.

Bella-Xiang 7y ago

The condescending language indeed makes people uncomfortable, especially for the newbie of this field. Funny experience and a good guide that encourages me in doing the same thing as the author: remove the condescending language from various documentation.