4 ms·
It's an improvement because it cut out all the adverbs. The tone of the essay is an unmistakable virtue signal. It tries to correlate the virtue signal with qu
by ulizzle 3y ago
It's an improvement because it cut out all the adverbs. The tone of the essay is an unmistakable virtue signal.
It tries to correlate the virtue signal with quality improvement, which is either cringe or disingenuous.
- spondylosaurus 3y agoCompletely disagree that this is a form of virtue signaling; everything the article outlines is reflected in the major documentation style guides (e.g., MMoS or the Google developer documentation style guide). - Don't make unsubstantiated claims about your product. - Don't discuss upcoming features or refer to existing features as "new" outside of announcements/release notes. - Don't make promises about uptime or other things that belong in an SLA—this can have nasty legal implications down the line. - Don't waste time with marketing-speak; your reader is either already using your product or is on the verge of using your product (and consulting the quality of your docs before they decide to move forward). - Don't use ambiguous language or cultural idioms that may confuse ESL readers. - Don't preface instructions with how easy it is to do something; every reader has a different level of experience and background knowledge. Also, if you say that your product is easy to use and then it actually isn't, it makes you look like an idiot. Or disingenuous. Or both.
- ulizzle 3y agoIf you completely disagree, keep in mind “completely” is also an adverb. Some frameworks sell simplicity (setup, maintenance) as a feature, so that adverb would be fitting. But this is just infantilizing and a lot of people (maybe a universal trait) are annoyed by that.
- spondylosaurus 3y agoWhat? Adverbs are fine; there's no industry-wide dictum against adverbs. I think you might be mad at something different than the principles I'm outlining here. These are accepted standards of technical documentation.
- ulizzle 3y agoThis is basic English grammar, something you should have learned in grade school.
- spondylosaurus 3y agoYour grade school taught you that adverbs are a form of virtue signaling?
- ulizzle 3y agoNo one will fall apart and burst into tears because of an adverb they read in the mountain of documentation we have to read to get the job done. Navel-gazing of the highest order.
- spondylosaurus 3y agoYou lost me there again, my friend. Technical writing stylebooks draw no correlation between adverbs and nervous breakdowns. You seem to be tilting at an entirely different windmill than the one I'm tending to.
- TheCoelacanth 3y agoThat's fine, but put your marketing copy in your marketing, not in your docs.
- Aeolun 3y agoIf good documentation is a virtue signal, then yeah, I guess?
- ulizzle 3y agoThis post is a shallow public display of faux moral superiority from the language police. I miss Linus Torvald's legendary snark and the epic flame wars of yesteryears.