4 ms·

Believe me, I am all for people having thicker skins and less entitlement overall. I believe offense is generally taken rather than given, and social media's cu

Believe me, I am all for people having thicker skins and less entitlement overall. I believe offense is generally taken rather than given, and social media's culture of constant outrage over some thing or another is a form of intellectual and moral decay. 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. The main problems with the "just simply" writing are twofold: 1. The "just simply" words are completely unnecessary filler. Good writing is stripped of superfluous filler words. Writing with lots of filler words is harder to read because scanning, parsing, and then discarding them is additional cognitive overhead. This technology shit is hard enough as it is, save the flowery prose for your poetry. 2. As others have mentioned, the tone of the "just simply" writing comes off as condescending because it implies the author is considerably more knowledgeable than the reader, that the reader doesn't know anything about the topic at hand, and that the reader will somehow reach enlightenment once they are on the same level as the author. It's not that I am personally offended by "just simply," it's just bad writing, and I won't read that kind of stuff unless I really have to.

tetha 4y ago
> 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.
- Kye 4y ago
  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.
- pclmulqdq 4y ago
  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.
grog454 4y ago
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.
- MrJohz 4y ago
  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.
yellowapple 4y ago
> 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.
- jjj123 4y ago
  But they are writing for an audience that is not as knowledgeable, so “simply” isn’t accurate for the audience, only the writer.
- cratermoon 4y ago
  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.
spondylosaurus 4y ago
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.
SoftTalker 4y ago
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.

tetha 4y ago

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

Kye 4y ago
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.
pclmulqdq 4y ago
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.

grog454 4y ago

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.

MrJohz 4y ago
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.

yellowapple 4y ago

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

jjj123 4y ago
But they are writing for an audience that is not as knowledgeable, so “simply” isn’t accurate for the audience, only the writer.
cratermoon 4y ago
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.

spondylosaurus 4y ago

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.

SoftTalker 4y ago

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.