DEV Community


Discussion on: How to remove condescending language from documentation

u8nc profile image
MiAn • Edited

I suspect those that use this type of language are seeking an alternative to dry technical descriptions and are seeking to make it more conversational and less alarming to a new user.

That argument may have held last decade, but most people have had enough exposure to technology that they just want the facts without all the verboseness.

Since Open Source is the context you are raising it in here, many such software tries to emulate more professional commercial offerings with the perhaps false premise new users haven't gone through their learning curves. That means the documentation writer ( whether the coder or UI designer or team lead ) assumes no prior knowledge of that industry sector in which it is used. So they have a choice, make it terse and clinical ( Documentation is a Legal Instrument after all ), or try to make it friendly in some way.

The problem is the "some way" the they choose. Carolyn has raised a valuable viewpoint of one such "some" way. I've never liked using used those terms, but not for the reasons the OP has raised. I've never seen them as condescending, but then I'm an arrogant old such-and such and a bit of a little Hitler when it comes to getting people to do what I want.

I can speak a few languages and am learning a few more from Arabic to various Asian ones, and many of those don't include incidental and decorative words that the romance languages do. ( French German English Italian Spanish etc. ) Quite often these words have come about to make phrases "roll off the tongue a lot easier, and give the speakers brain time to engage in what to say next, or from the listeners point of view time to assimilate what they've heard.

And that's where the problem arises. People try to put on paper what belongs to speech. It very rarely works. It's like trying to cross pollinate a hybrid tree from the Conifer group with a Hardwood. If its not condescending its plain awkward. Leave it out.

Then there's a separate minefield when these have to be translated, either in word-for-word or thought-for-thought.

I tried once to make a humorous interplay between the unsaid instructor that is the manual and the learner as Preying Mantiss Mastah and Humble Glasshoppah. I decided that humour is too dangerous, even before going cross cultural with it.

What worked in various places was to be a bit verbose and explain the reason for the prominence of the UI being as it was with other controls hidden behind a tab, and implied therein was the "just simply" without being said.

It's a skill, and I think there are better people than me with some of the docs I've read.
Thanks again for raising it.