Hacker News Reader

> HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with. They tend towards considering only what they want the reader to do or think, not necessarily who the reader might be or what _they_ want to get out of the writing.

In my experience - and as a problem on top - writing seems to be one of these crafts in which experience accrues slowly and usually only with good readers.

For example, I've removed "just simply" from my usual documentation vocabulary by just simply following a few steps - sorry, that was too tempting to leave out :) But one realization that drove me away from "simply" was: Simply usually is an imprecise word and this lack of precision opens up doors for misunderstanding. Often when I used simple, I meant it as "simple process" vs "convoluted process". In those cases, I replaced it with "straight-forward" or similar words. This is intended for the reader to judge if they are getting into a process you can just do during a boring meeting, or if they are about to enter some escher-esque rabbit hole.

However, this realization was mostly driven by good readers who informed me about possible misinterpretations my choice of words offers to them. So, even if it sounds nit-picky, go ahead and point out such things and start looking for those. It'll make you a better writer, and other writers around you better.

The best thing I ever did for my writing was subject it to editors and beta readers. It can be hard to find friends who are willing to pick your writing apart, but they're the best kind.

Another way to put this advice on how to write with precision is: carefully consider any use of an adverb in formal writing (pun intended). Most adverbs in formal writing can be replaced by using a better adjective or verb. For some reason, adverbs like "simply" and "quickly" make people feel bad when the process isn't simple or quick, but using words like "straightforward" does not.

Technical writer checking in to cosign everything you've said here. Most style guides advise against this kind of language for the exact reasons you outline—it adds nothing to documentation and it's pithy marketing-speak.

Don't hype up how easy it is to install your product... just tell us how to install the damn thing! :P

> HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with.

Also, completely on point, although in my experience product managers are far worse offenders than engineers.

> the tone of the "just simply" writing comes off as condescending because it implies the author is considerably more knowledgeable than the reader

If the author of some library was not considerably more knowledgeable than myself, then I probably wouldn't be poring over said library's documentation.

Yes, the author of that library knows more about that library. That doesn't mean they are generally more knowledgeable than me, and in fact they may be quite ignorant about the specific problem that lead me to investigate and learn the library in the first place.

But they are writing for an audience that is not as knowledgeable, so “simply” isn’t accurate for the audience, only the writer.

There's room for debate over some of the advice in Elements of Style, but "omit needless words" is a great one that every expository writer should take to heart. The advice to use common words in favor of "fancy vocabulary" is also good.

I agree in general that they're often misused, but "just" and "simply" do have a place. Specifically in place of "only" or "instead", or to set up a subjective comparison.

A: I'm going to do X, Y, and Z.

B: If you just do X, we'll meet the requirements.

A: I tried X Y and Z to fix my problem.

B: You can simply reinstall the IDE.

I think "simply" as a synonym for "instead" is part of the problem here. "Instead" is probably the better option in most cases. For example, in the case you gave, "instead" is the clearer word choice because it clarifies that you are (only) presenting an alternative course of action, rather than offering a value judgement on that action. Similarly, "only" is generally better than "just", because again, it tends to be less loaded and more explicit.

This won't be applicable to all writing - writing for entertainment or to make an argument will look very different - but in technical writing, clarity is key, and words like "just" and "simply" are usually less obvious than their "only" and "instead" counterparts.