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