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

261–270 of 299 posts

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

#261

Post by Uvix »

Smaug123 wrote: post #177

I'm surprised nobody has pointed out yet that "Mailers are another way to render a view" has lost information that was present in "Mailers are really just another way to render a view.". The author of this post appears to want to adopt the most infuriating traits of the MSDN documentation: namely, converting all documentation into a list of facts ("Mailers are another way to render a view", "a common use of mailers i…

Both versions are bad, because in both cases the first sentence says that mailers are "another way to render a view", while the second sentence says they are another way to "send" an already-rendered view.

> I mean, is it rendering a view or isn't it?!

It is rendering a view, and both versions make that clear. There's no contradiction in the rewritten version.

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

#262

Post by lucakiebel »

WastingMyTime89 wrote: post #48
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:/…

"Simply" when used in the sense of "without addition, alone" is perfectly fine. I find the issue people have is not really with the word simply but with bad documentation and badly designed tools. That’s not going to be fixed by avoiding one word.

Ok, so at least I‘m not the only one using simply that way

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

#264

Post by has_many_books »

vinaypai wrote: post #225
has_many_books wrote: post #111

Earlier quoted context omitted.

It wasn't an example: it was copied and pasted from the Rails guides at the time.

Oh wow, okay. That sounded so bad I didn't think it could possibly be from the real documentation for a pretty popular product.

I know: bonkers!

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

#265

Post by blacksoil »

> If someone’s been driven to Google something you’ve written, they’re stuck.

This is not true. When I evaluate new technology to decide whether to use it or not, I tend to Google or HN around to see what people think about it. The words "just" or "simply" can be a good expression somebody uses to express their opinion about the library.

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

#266

Post by kazinator »

abtinf wrote: post #49
kazinator wrote: post #39

Earlier quoted context omitted.

So, it's off limits in a technical text to say that, say !(!a && !b) simplifies to a || b, or anything else in a similar vein?

In English, the math jargon term “simplifies to” means roughly “is equivalent to this less complex form”. It does not connote difficulty.

It absolutely denotes difficulty. E.g. more machine cycles are needed to traverse the original expression tree that has more nodes.

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

#267

Post by novok »

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…

Newbies get into loops by thinking the solution is simple when it's complex from their perspective and can go off rabit paths and waste time. Kind of like the opposite of overthinking a solution when the solution is simple. It's a writing linter.

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

#268

Post by firexcy »

desro wrote: post #196

I don't share the author's POV describing this sort of thing as "infuriating" or anything else that dramatic, but the before-and-after documentation example was definitely more readable and clear (I've never worked with rails [ruby?]). So I support the overall premise here. It's nice to read documentation that is at least verbose enough to give you additional keywords to search with if you need more help, and I do fe…

> a lot of the tutorials available on Digital Ocean are actually good examples of this

Second this (although the qualities of DO’s tutorials can vary greatly). Indeed, their “Technical Writing Guidelines” [1] agree with the author:

> We avoid words like "simple,” "straightforward,” “easy,” “simply,” “obviously,” and “just,” as these words make assumptions about the reader’s knowledge. While authors use these words to encourage and motivate readers to push through challenging topics, they often have the opposite effect; a reader who hears that something is “easy” may be frustrated when they encounter an issue. Instead, we encourage our readers by providing the explanations they need to be successful.

[1] https://www.digitalocean.com/community/tutorials/digitalocea...

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

#269

Post by stjohnswarts »

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…

Is it really a big deal that people would like to just simply ID it as a grammar issue and basically is simply a useless phrase as it will be simple for some but not so much for others and let them judge how simple it is for themselves?

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

#270

Post by throwawaaarrgh »

peoplefromibiza wrote: post #118
throwawaaarrgh wrote: post #109

Earlier quoted context omitted.

I could tell you you're missing the obvious answer, but that doesn't help you understand the thing you're missing. I could tell you the YouTube tutorial that starts from scratch has a very simple and obvious reason why it starts there, that a lot of other people get that you don't. But that doesn't help you either. And I could tell you that infantilizing someone who's having a hard time understanding something is the…

> YouTube tutorial that starts from scratch has a very simple and obvious reason why it starts there what's the reason in your opinion? Because in my opinion a programming tutorial that starts from installibg the IDE is like a recipe tutorial that starts from how to use a gas stove. it should be two different tutorials, at least It is clearly important to understand how an IDE works, but that's the kind of knowledge…

One of the things I do for a living is write documentation. I have the privilege of supporting a lot of different types of users. And within each type of user, there is variability.

For every document I write, there are always a couple people for whom my document fails. It's not because they're stupid, or because I am. It's because communication is hard, and different perspectives change how information is processed. In addition, in many cases, there's simply a different use case that my document didn't account for because I didn't think of it or run into it.

So much of the time, I need to amend documents after the fact. I may need to clarify a statement, or provide alternate instructions. Often it's a detail that I thought should be universal but wasn't. And often users will simply have done something different beforehand, or out of order, or in some way not in accordance with the intended instructions.

Therefore, if I want a user to be successful with my document, it has to be complete, and thorough, and be tested by different people. It needs to not make assumptions, and it needs to be clear and concise so it can be followed in one go.

If you start getting fancy and make 50 different documents for different steps, because "logically" that makes more sense, what you will find is the user will run into a problem that the two separate documents didn't consider when taken together. Then the user will stop and try to find someone to fix their issue.

If you don't want to be tied up in support calls your whole life, one complete document is the best solution. And if you're a user who just wants to try out some sample tutorial, one complete document is the most likely to work for you without taking up more of your time.

The YouTube video that shows you installing the IDE is superior to one that doesn't. And for pete's sake you can always skip through it.

Post reply on HN