Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Just Simply – Stop saying how simple things are in our docs

justsimply.dev

Post reply on HN
Print view View original

241–250 of 299 posts

Re: Just Simply – Stop saying how simple things are in our docs

#241

Post by kristopolous »

codeflo wrote: post #70

Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…

It signals the authors incompetency and is a red flag their code is a bug ridden hot mess caught up in ego stroking bullshit.

Simple, easy, lightweight - any project with that in the name is a sprawling trashpile.

Re: Just Simply – Stop saying how simple things are in our docs

#242

Post by spondylosaurus »

imgabe wrote: post #148
Muromec wrote: post #88

Earlier quoted context omitted.

>What I wonder is: Why is this so personal? Looking at example given at this page, before the edit -- it looks like whoever wrote the library is being proud of this little trick they just invented. Look, look, mailer is just another kind of a view! Appreciate how neat it is that we don't invent another high-level concept but reuse existing stuff in a slightly different way. This is personal. Example on the right skip…

Nah we don’t need to strip out every ounce of personality from something someone was kind enough to write and share for free. Anyone whose delicate sensibilities are so offended can just simply write whatever free library they’re using themselves.

This advice extends far beyond free libraries (and the linked article makes no indication that it's specific to that context). I've encounter all kinds of B2B SaaS docs full of worthless bloat, and I've written docs in the face of pressure from product teams who want to turn documentation into a Look How Cool We Are showcase.

And docs can be clear and straightforward without reading like stereo instructions—you can convey plenty of personality through tone and voice.

Re: Just Simply – Stop saying how simple things are in our docs

#243

Post by _gabe_ »

codeflo wrote: post #70

Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…

I completely empathize with this sentiment and understand where you're coming from. However, I've been writing tutorials and documentation for awhile now, and while editing my videos I realized that I would often say "see, simple" after explaining a topic (which is equivalent to just simply in my opinion). I realized that 99% of the time I said that, it was filler and unnecessary, almost like a nervous tick.

Aside from that, of course it's simple for me! I'm the one writing the documentation or creating the tutorial. I've tried to simplify the material into digestible steps. However, this also means I know the subject at hand inside and out. My target audience doesn't necessarily know it as well as me.

So, instead of saying, "see simple" in my tutorials, I began asking myself, "is this concept truly simple for my target audience?" If it isn't simple, then that points out an area I need to clarify and simplify further. I only consider the video/documentation done when I can truly say to myself that the technical content is concise and simple enough for my target audience. This leads to better technical writing (no unnecessary filler), and it leads to a hopefully thoroughly thought out description of the material at hand.

So I don't believe people are being babies or shamed into quitting their careers over a misplaced "simply". Rather, I think they're subconsciously understanding that the writer of the documentation wasn't ruthlessly cutting down the material. I think "just simply" often points to lazy writing, and people pick up on that. Good documentation is ruthlessly concise, truly simple (as in its reduced to the smallest piece of information possible), and it conveys the necessary information quickly.

Re: Just Simply – Stop saying how simple things are in our docs

#244

Post by SoftTalker »

bityard wrote: post #194
codeflo wrote: post #70

Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…

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…

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.

Re: Just Simply – Stop saying how simple things are in our docs

#245

Post by lamontcg »

codeflo wrote: post #70

Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…

More controversial opinion is that there's too much ego-stroking fluff in general and everything is "perfect" and "elegant" and "awesome" and "simple", etc, etc, etc. Always reads like appeals to narcissism to me.

Re: Just Simply – Stop saying how simple things are in our docs

#246

Post by gumby »

I understand the author’s point yet think it’s OK.

Why? Because when I encounter “simple” in that context I read “If you understand the domain this package allows you to perform calculations (or whatever) and will operate in a way you will expect”.

Some examples: IEEE floating point is a simple FP standard, even though the document is really long and full of non-obvious cases and a couple of footguns for the naive. It’s simple for someone doing serious numerics (and even simple for a most common cases with a little training) because someone put the hard work in, so the user doesn’t have to code up allot of infrastructure.

MS word makes it easy for someone like me to change font sizes, center some text etc, but a sophisticated designer probably fights Word’s DWIM and would prefer a more sophisticated tool with more knobs, because that would be simpler for hem to use.

And so on.

Re: Just Simply – Stop saying how simple things are in our docs

#247

Post by spondylosaurus »

ulizzle wrote: post #197
jonahx wrote: post #195

Earlier quoted context omitted.

It's unfortunate that this is the top comment, because the "after" samples are clear improvements. This is good old-fashioned writing advice, no different from Strunk and White's "Omit needless words" -- just tailored to developer documentation where a handful of specific needless words flourish. The main reason to remove these words is that they are fluffy, superfluous marketing speak. Do some people also find them…

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.

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

Re: Just Simply – Stop saying how simple things are in our docs

#248

Post by WilTimSon »

codeflo wrote: post #70

Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…

One of the rare times where I agree that someone being infuriated by these words is a bit ridiculous. It's not like they're offensive or emotionally manipulative, it's merely a matter of someone's style of writing or just a means of encouraging someone to do the task that might otherwise seem daunting by virtue of being one of a hundred tasks they have to do that day. It can be annoying but complaining about hyperbolic words and then saying they are "infuriating" is a tad ironic.

Re: Just Simply – Stop saying how simple things are in our docs

#249

Post by paulddraper »

codeflo wrote: post #70

Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…

Words have meaning.

And 92% of the time, "just" or "simply" have no useful meaning.

Re: Just Simply – Stop saying how simple things are in our docs

#250

Post by steve_adams_86 »

apricot wrote: post #123

As a math professor, I had an epiphany about the word "easily" several years ago. In my course notes, I used that word to mean "I guarantee you don't need any additional ideas here, just do the obvious thing." Nothing more was meant. But I realized that many students either didn't think the obvious thing was really that obvious, or maybe realized it but were reticent to follow that path because it invoved some tediou…

I suppose too that if something truly is easy or simple, it should be self-evident. What is the purpose of taking the time and energy to point out that something isn’t difficult? If it were true, a person would likely discover it themselves readily enough.

I find this kind of writing (and thinking in general) fairly commonplace. It’s a good exercise to take a step back and wonder: why did I write that? What did I actually mean by it? Is it necessary to state X or Y, or am I using it implicitly for some communicative purpose that should be explicit?

Stuff like this is why writing is actually quite hard, in my opinion.

Post reply on HN