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

81–90 of 299 posts

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

#81

Post by WesolyKubeczek »

paradox242 wrote: post #57

I get this a lot while reading about something new which I have heard might solve my problem, or while better trying to understand a system already in place. The documentation begins with a comforting high level description that is vague enough to sound like it might fit my use case, but then abruptly transitions into a table of contents listing the minutiae of interfaces, API calls, system components, without giving…

I’ve seen worse.

— an emoji-laden intro employing borderline UwU-speak

— jumping into API reference immediately after

— the reference is auto-generated with half of it being stubs, implying you should throw it away and just simply read the code

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

#82

Post by newswasboring »

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 dont know about taking it personally, but it is very annoying to me. It is also misleading, because most of the times it is not simple by most definitions. I like my documentation to be concise and give me information, not make effort estimates for me :D. I know it's a silly point, but it is very grating to read. I would file this under bad writing practice.

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

#83

Post by WesolyKubeczek »

EGreg wrote: post #25

It’s like when I was growing up, I always found it hilarious that the seller on TV touted a “low low price of ONLY xyz”, and they marveled at their own offer! As a kid, I realized that this is silly… it us the buyer who determines if the price is affordable or not. Most advertising in the last few decades just spouts nonsense in an effort to get you to buy something.

You’d be amazed how many people still watch this shit in 2023 and even buy it, when

1) you can quite easily* find what cheap product is this a rebrand of

*admittedly not so easily since Google became extremely enshittified in the last fiveish years

2) drop that product into any old ebay or a price comparison engine and marvel at the markups they rack

3) find reviews of the same and see how those products come apart when you look at them funny, or are made of plastics known to cause cancer wide outside California, or some shit

But then again, it’s my bubble, outside of it it’s far from “obvious”

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

#84

Post by ModernMech »

kstenerud wrote: post #61

Now that I've written a few specifications (which tend to have a much higher explanatory burden), I've come to appreciate just how difficult it is to write introductory material to a subject that you're an expert in. Like any skill, it takes a lot of practice.

Lol, yeah the first time I attempted it, someone got so frustrated they posted an expletive laden issue on the repo. There’s some real latitude to go wrong here!

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

#86

Post by tarkin2 »

It's annoying and sometimes demeaning and often tactical when managers use it.

In docs it can be annoying when there's assumed knowledge and skills.

And it adds nothing except to indicate how another may find the activity--why bother adding it?

Simply improve your docs, people.

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

#88

Post by Muromec »

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…

>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 skips this part and focuses on how to use things.

Being proud of "this little trick we invented" is good ofc, but maybe it's place is in a conference talk or into video of something. Maybe whoever is reading the doc is not your mom and doesn't care right now.

It's a bit of a cultural shift from a community of cool people showing cool stuff to each other to more "it's just a job" kind of attitude. If you aren't there to appreciate clever tricks, it's just noise.

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

#89

Post by Fnoord »

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.

Clearly, there are other words which sound condescending.

Reading text (documentation, for example) is more enjoyable when it inspires one's curiosity instead of belittling them on things which are simple, easy, obvious, clear, etc. Although humor helps, makes it stick.

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

#90

Post by brunooliv »

My stance is really not in favor or against using (or overusing) a word from a "blacklisted" set, it's more that usually the structure doesn't cater well to the audience and on top of that it adds a lot of unnecessary fluff. If I need to download X dependencies but two of them need to be version 1.2.3, by all means tell me it's all super simple to do, idc, really. But give me the exact dependencies that NEED that version for the thing to work. Worse than this unnecessary fluff and eagerness for simplicity or wtv is having incomplete instructions that lead to a non-working setup by the end. Proofread them by EXECUTING them and then, as long as it works, be a Shakespeare about it. There seems to be a lot the expectations of things being broken and a kind of tragedy of the commons being the standard.
Post reply on HN