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

111–120 of 299 posts

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

#111

Post by has_many_books »

vinaypai wrote: post #80

I don't entirely disagree with the sentiment, but the example is so contrived. The problem with these sentences isn't that the word "just" and "simply" are somehow upsetting to the reader but that they're clumsy sentences. "Mailers are really just another way to render a view. Instead of rendering a view and sending it over the HTTP protocol, they are just sending it out through the email protocols instead. Due to th…

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

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

#112

Post by matsemann »

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…

> Why is this so personal?

It's simple to understand, really. How come you don't get this trivial thing?

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

#113

Post by throwawaaarrgh »

_RedPanda wrote: post #69

I agree that words like simply and just should not be used in documentations, but are people really getting upset about it? I couldn't imagine being this fragile

Think a little harder, then. It was written for a reason. They even bought a domain and hosted this one page, for a reason. You think they did all that because they were fragile?

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

#114

Post by ekimekim »

dale_glass wrote: post #92

While we're here, could we also please have clear separation between commands and data? Eg, I hate stuff like: $ bin/rails generate scaffold user name email login Which is it? $ bin/rails --generate=scaffold --user=name --email=login Or: $ bin/rails --generate=scaffold --user=username --name=fullname --email=address --login=login_name Or: $ bin/rails --generate --scaffold=user --name=fullname --email=address --login=…

The long-standing convention here, particularly for command line usage, is that:

- String literals should be in lowercase (because by convention commands, argument names, etc should always be in all-lowercase, eg. "git cherry-pick" not "git cherryPick" or "git CHERRY-PICK")

- Metavariables (stuff the user should fill in) should be in ALL-CAPS.

- Not as strictly adhered to but still useful, [optional part] and {repeatable part}.

So eg. your example might look like:

    $ bin/rails generate scaffold --user=NAME --email=LOGIN
and an example usage would then be:

    $ bin/rails generate scaffold --user=ekimekim --email=ekimekim@example.com
As far as I'm concerned, for documenting command usage, there is no excuse not to use this scheme.

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

#115

Post by [deleted] »

newswasboring wrote: post #82
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.

[deleted]

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

#116

Post by incone123 »

VWWHFSfQ wrote: post #99
incone123 wrote: post #67

Earlier quoted context omitted.

There's an explicit caveat on chat gpt: limited knowledge of the world and events after 2021. You're asking about 22.04.

Right so that why it's not useful for this

Re-reading the gpp, I assume the arg confusion was true in earlier editions of Python so maybe worth seeing how it handles the question as applied to those earlier editions.

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

#117

Post by zabzonk »

codeflo wrote: post #105
smcl wrote: post #98

Earlier quoted context omitted.

This is such a bizarre take. The post is about removing some unnecessary wording from technical documentation that doesn't add anything, and as an aside can sometimes imply complex tasks are simpler than they are to the detriment of the app/library/service it's documenting. I have no idea why you'd think this implies some personal failing or that it is advice for "babies"

> The post is about removing some unnecessary wording from technical documentation that doesn't add anything, and as an aside can sometimes imply complex tasks are simpler than they are to the detriment of the app/library/service it's documenting. I'm not sure that's a fair summary of the article. I just reread it: at no point does it suggest removing superfluous words in general , it's specifically about "words such…

john lennon once said "never use 'just' in a lyric - it's lazy" (i paraphrase) and i think he might have had simmilar opinions on such things as "trivial". sadly, we will never know.

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

#118

Post by peoplefromibiza »

throwawaaarrgh wrote: post #109
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 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 that should be implied when you watch a programming tutorial.

Otherwise you need to learn two things at the same time.

Besides, IDE are usually complex enough that the two sets of skill don't overlap, so if the tutorial focuses on the programming and skims over installing the IDE, it is assuming that you can "simply" or "trivially" install an IDE such as Jetbrains Idea and be immediately ready to use it proficiently enough to learn something else with it, instead of fighting it to get things done. Which is usually the case, when I teach programming at work I focus on the programming using slides or some basic live coding using a very basic editor (vanilla sublime for example), because if I start using IDE features, people start making a lot of questions on how to do the things that I am doing that I don't even realize that I am doing them without even thinking about them, to the point that it becomes an IDE focused training. Showing that you can't take for granted that installing an IDE is a good starting point. It raises more issues than it solves.

I'm quite sure it would have been much harder for me to study Italian literature while I was learning how to read.

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

#119

Post by EdSharkey »

brunooliv wrote: post #90

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 ver…

It bothers me when someone good/bad naturedly corrects me on "blacklist" and encourages me to say "blocklist". I figure that stems from either overactive empathy or is a power play. Please continue to say "blacklist".

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

#120

Post by Semaphor »

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.

"Obviously" will always remind me of math classes in university. Sometimes the professor would use it as a joke, sometimes they used it normally while still stumping everyone else.
Post reply on HN