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

161–170 of 299 posts

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

#161

Post by perrygeo »

The problem with using "simple" is that it's ambiguous. Are you talking about the opposite of sophisticated? the opposite of difficult? the opposite of complex? It has virtually no meaning without context.

So if you're tempted to write simple, remove it and say exactly what you mean.

Often times, documentation writers say "simply do X" when they mean "as a prerequisite, this document assumes the reader has an understanding of Y such that they can accomplish X without any further instructions". There's nothing wrong with having prerequisites; you have to assume the reader has some knowledge upon which to build. Make that explicit rather than hidden behind a "simply".

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

#162

Post by thunky »

ianbutler wrote: post #141
thunky wrote: post #131

Earlier quoted context omitted.

So you're saying people as a whole don't change behavior over time? It's not possible that the average modern software developer is just a bit more sensitive about their work than a welder was in 1950?

I've known people who talk about their welding skill and would be unhappy if you pointed out their joint looked like crap. People, in general, are sensitive about anything important to them.

I was trying to compare equivalent professions across time periods, not to suggest that welders are any different than developers.

I would not be surprised if modern day welders get offended by their equipment manual as well.

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

#164

Post by adolph »

wdfx wrote: post #38
sametmax wrote: post #3

It's a more and more popular opinion: - Why not tell people to "simply" use pyenv, poetry or anaconda ( https://bitecode.substack.com/p/why-not-tell-people-to-simpl... ) - Don’t use the word ‘simply’ ( https://jameshfisher.com/2017/02/22/dont-use-simply/ ) - Stop using ‘simply’ in tech instructions ( https://www.parkersoftware.com/blog/stop-using-simply-in-tec... ) - Don’t say “simply” in your documentation ( https:/…

Similarly, one should never state that something is "obvious". I catch myself sometimes starting a sentence with "Obviously," and usually stop myself at that point and restart.

At first I agreed with you in that my spouse had a negative response to me referring to a particular person, method, place or thing as “famous” when she was not aware of the person. I’ve learned to omit it or say “well known in some circles” or the like.

On the other hand, maybe these phrases like “simply” or “obviously”are less-than-consciously used on the part of the speaker/writer to acknowledge that this reference may already be known to the listener/reader. In that it reminds me of various England-Englishisms that mean the opposite of their plain definitions.

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

#167

Post by eric-burel »

My fav game with a new tool is to take "simple" features and break them on equally simple use cases that are not documented. The most popular libraries are with no surprise the ones that resist this game the best. To give example, I like React and Next.js new beta documentation because they do not stick to being a reference but also explain the rationale and show real-life usage as much as possible.

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

#168

Post by btown »

“With fewer lines of code” is not the same thing as “simpler” - particularly, if it’s an abstraction that requires the user to understand the underlying mechanics, the more verbose code may be significantly more self-evident.

If you’re writing even an internal API and this thought pops into your mind, put yourself in the shoes of a junior colleague and ask yourself - or ask one directly! - if a little bit of boilerplate is actually a good thing.

And, to the OP’s point, if you do decide to make these abstractions, using terms like “brevity” rather than “simplicity” can be a big part of gaining adoption.

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

#169

Post by tristor »

Given the state of software documentation in general, I am okay with any word choices the author wants to use, even the downright offensive, as long as it means they actually document the software thoroughly. I have way bigger fish to fry than the emotional response I have (or don't have) to a given word.

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

#170

Post by abootstrapper »

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…

Because when you use phrases like “just simply” [do something actually hard], your stakeholders read that and say things like, “why did this take a whole sprint to implement? You said you just had to [do something hard].” There’s no reason to downplay the difficulty of your and your team’s work.

Further, we’re adults, as you say, so let’s be adults and take the time to consider our readers position and how our writing might be interpreted. You’re doing no one any favors by refusing to be empathetic.

Post reply on HN