DEV Community

loading...

Discussion on: How to remove condescending language from documentation

Collapse
tehunk profile image
TaeHun

Perhaps "condescending" is not the best word to describe such expressions, but I can relate to the sentiment. It has annoyed me many times when documentation claims it's "easy", but there was an "unclear" assumption that didn't make things easy in practice. In general, one should strive to convey only reproducible facts in documentation without subjective/unnecessary expressions. If you claim something is "simple and easy" in the documentation, show me the evidence. I've seen tutorials and docs with phrases like "just type xxx". Do you really need that extra word "just" there? How does that improve readability or change meaning? Doc is not an essay or pitch.

Collapse
gido profile image
Gilles Doge

The Symfony documentation use the term "belittling". Maybe it fit you best: "Avoid belittling words", github.com/symfony/symfony-docs/bl...