Just Simply – Stop saying how simple things are in our docs (justsimply.dev)

Article summary

The article discusses how using words like 'simple', 'easy', and 'just' in technical documentation can be alienating and condescending to readers who are struggling to understand the material. It suggests that these words can make readers feel worse about not understanding something and can get in the way of learning. The article provides examples of how removing these words can improve the clarity of technical writing. By avoiding these words, writers can create more effective and supportive documentation.

Main themes

• technical writing
• condescending language
• clarity and simplicity
• adverbs and adjectives
• documentation best practices
• reader experience and empathy

What commenters say

• Avoiding words like 'simply' and 'obviously' in technical writing can improve clarity and reduce condescension.
• Some adverbs, such as those ending in '-ly', can be removed from technical writing without loss of meaning.
• Using words like 'simple' and 'easy' can be discouraging to readers who are struggling to understand the material.
• The issue with words like 'simply' is not the word itself, but rather the implication that the material is easy to understand when it may not be.
• Comparatives like 'simpler' can be used without issues, as they provide a relative measure of complexity.
• Humor and inspiration can be more effective in technical writing than condescending language.
• The use of words like 'obviously' can be seen as a way to acknowledge that a reference may already be known to the reader, but can also come across as condescending.
• Depth and breadth are both important in technical documentation, and avoiding shallow tutorials and marketing lingo can improve the overall quality of the documentation.