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

131–140 of 299 posts

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

#131

Post by thunky »

rco8786 wrote: post #96
vrnvu wrote: post #79

Earlier quoted context omitted.

I agree with your point. Nowadays, people seem to be overly sensitive about their code and the way we communicate, among other things. It's important to remember that the code is not a reflection of ourselves, and not everyone will be pleased with it. Some will provide good guidance, while others will not. Therefore, we should remove our ego from the code. Code is like a lollipop that we enjoy, but then discard once…

> Nowadays, people seem to be overly sensitive about their code and the way we communicate, among other things. If there's one thing I've learned in life, anytime you see "Nowadays" or "these days" or something similar, you can be guaranteed that whatever statement follows it is a universal truism about the human condition that recency has no bearing on. People are sensitive about their work. And sensitive to how we…

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?

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

#132

Post by ellisv »

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…

Whenever my professor said "it's easy to show" and then moved on it felt very hand wavy. The steps weren't obvious to me and didn't become more obvious as the course went on because no one taught me how to think of the "obvious" thing.

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

#133

Post by vivegi »

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

Its trivial. The obvious solution is to just simply read the extremely friendly documentation. /s

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

#134

Post by javajosh »

ellisv wrote: post #132
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…

Whenever my professor said "it's easy to show" and then moved on it felt very hand wavy. The steps weren't obvious to me and didn't become more obvious as the course went on because no one taught me how to think of the "obvious" thing.

The worst situation in my college experience was when a prof would go over some mundane part of a proof in excruciating detail, and then hand-wave the important part. I realized later in life it was because they prof didn't understand it, either.

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

#135

Post by tremon »

charcircuit wrote: post #7

If simple things like running a command isn't simple for you then the docs were written for a different target audience than you. Just because I'm checking the docs it doesn't mean that something isn't simple. It is just impossible for me to know or remember everything about everything even if some of those things are simple. If you aren't the target audience that doesn't mean you can't use it, you just might end up…

Indeed. Or, put differently, proclaiming things to be "easy" in your documentation mainly serves to scream "go away!" to new users.

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

#136

Post by nickjj »

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

In your example you're using rails but isn't this a problem with every command line tool ever that has positional arguments?

    cp a b
    rm -f a b c
    etc.
Is "a" a sub-command of cp or is it data? Is "a" in the rm command data or a value for the -f flag?

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

#137

Post by Waterluvian »

I have embraced the idea that nobody wants to read what I write.

I think that everyone is going to close my document at any moment, so I communicate as clearly as possible.

My tech writing reads like it’s for kids, but coworkers seem to like it.

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

#138

Post by teddyh »

bombcar wrote: post #97
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=…

Especially when we have the entirety of modern monitors available to us, use color to indicate which parts of the command/code are mandatory/boilerplate and which are optional, and which are the actual "values" you'll be using.

Color might not be available, like here in HN comments.

In older texts, the convention was common, but became less so probably due the emergence of HTML. Nowadays, I most commonly see the $SHELL_VARIABLE convention. Man pages use UPPERCASE_ITALICS (or uppercase underlined on terminals).

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

#139

Post by hnarayanan »

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…

And as a math student, I found myself using this as a strategy in reverse.

Finding myself in a tenuous part of a proof, I would say things like “clearly one can see that,” and jump a few steps. I think I was doing this to put the person looking at my work in the back foot, and it might’ve worked a couple of times!

Post reply on HN