4 ms·
This is just yet another politeness law, adding some more words we shouldn't use. There is a useful message though: make writing clear and unadorned.
by robertlagrant 4y ago
This is just yet another politeness law, adding some more words we shouldn't use. There is a useful message though: make writing clear and unadorned.
- delta_p_delta_x 4y ago> There is a useful message though: make writing clear and unadorned I think this is the key takeaway. From the example in the article, phrases like 'just', 'painfully simple', 'just another way' aren't instructive nor objective, but decorative and subjective. Documentation should have exactly one purpose: to instruct. There ought to be no mentions of difficulty, or obviousness, or triviality, or any other smart-aleck commentary. It ought to have a direct, clear tone, such as 'do X, which causes Y. Now do A and B, which requires C.' and so on.
- jtwaleson 4y agoI see it differently. If you are writing documentation for a system you know a lot about, things are completely simple for you right then right there. But as we all know in 6 months you'll look at your own code and think "who the ... wrote this?". So avoiding the word "simple" isn't about accommodating the 5% of your least intelligent users and dumbing down the content, but the > 90% who are not so into the topic as you are right now.
- robertlagrant 4y agoClarity, yes. But not specific rules. Or we're back to the Plain English Campaign simplistic "only write in the active voice" silliness.