How to remove condescending language from documentation | Hacker News Reader

How to remove condescending language from documentation

dev.to

3 pointsKye6 comments

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.

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!

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.

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).

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.

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."

Reply on news.ycombinator.com