Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

If someone’s having to read your docs, it’s not “simple”

justsimply.dev

Post reply on HN
Print view View original

141–146 of 146 posts

Re: If someone’s having to read your docs, it’s not “simple”

#141

Post by thiht »

Kronen wrote: post #136
Dashron wrote: post #106

Earlier quoted context omitted.

It's not a good feeling when you find something "simple" to be hard. Few tasks are easy when you're a new programmer still wrapping your head around conditionals. If my docs might be used by a new programmer I try to avoid alienating my users with the word simple.

The real question and a better post than the original post would be: Are people living in the 21st Century too easily offended? But it's a rhetorical question...

Yeah, maybe not being offended just because of the word "simple" would be a good start.

Re: If someone’s having to read your docs, it’s not “simple”

#142

Post by mgoetzke »

handrous wrote: post #17
MattGaiser wrote: post #12

50% of the questions on Stack Overflow are probably because the documentation was not great in the first place. I am surprised how much configuration/installation time I spend on there.

Something that bugs the hell out of me is any file-location or file-name configuration-by-convention thing where every example doesn't clearly state WTF file it's supposed to go in and link to a full example to provide any necessary context. "Gee, I guess I'll scan the whole page... nope, not anywhere on this page, now I get to click around your docs menu trying to figure out where this goes. Thanks." Half the time I…

Oh yes. Really big pet-peeve of mine. Happens a lot with auto or semi auto-generated documentation.

Re: If someone’s having to read your docs, it’s not “simple”

#143

Post by Dashron »

Kronen wrote: post #136
Dashron wrote: post #106

Earlier quoted context omitted.

It's not a good feeling when you find something "simple" to be hard. Few tasks are easy when you're a new programmer still wrapping your head around conditionals. If my docs might be used by a new programmer I try to avoid alienating my users with the word simple.

The real question and a better post than the original post would be: Are people living in the 21st Century too easily offended? But it's a rhetorical question...

I didn't use the word offended.

Feeling offended is a very different emotion than feeling alienated.

Re: If someone’s having to read your docs, it’s not “simple”

#144

Post by astrange »

segfaultbuserr wrote: post #54
astrange wrote: post #2

Another thing you should not do is name things “fast”. It will end up not being fast (esp when you find the next faster thing) or else someone will find security holes in it.

So far, Fast Fourier Transform and Quicksort still holds up well (there are faster algorithms, but both remain adequate choices for general use). But I do agree with you, they're exceptions rather than the rule, e.g. Fast Ethernet , only 100 Mbps ;-)

FFT does, but the FFT library fftw ("fastest fourier transform in the west") is no longer the fastest from what I understand.

FFmpeg originally stood for "fast forward" but no longer means anything. They do have this problem where they need to replace older APIs with newer ones - their approach is to give the newer ones names with "2" "3" stuck on the end instead of "fast" "faster" etc.

But there are some problems in there, there's something called "simple IDCT" which I have to admit I never fully understood.

Re: If someone’s having to read your docs, it’s not “simple”

#145

Post by pistoriusp »

EastSmith wrote: post #118
pistoriusp wrote: post #67

As a programmer I've realized that one of my special skills are that I read the docs. It's such an understated skill.

I _do not read_ the docs. I read the readme in githib, if there is not enough information in it for my use case, I may continue searching. Also, when I find a lib, I want to read some user stories, not 20 pages of documentation in yet another doc format. Simple user stories. If you need to do A, here are 3 lines. If you need to do B - here are 5 lines. If your lib lacks these user stories, I will probably skip it. Or…

I think you're getting downvoted because none of what you mentioned isn't docs. You do read them, you just read a specific type of documentation.

Re: If someone’s having to read your docs, it’s not “simple”

#146

Post by swalladge »

anm89 wrote: post #9

I've had a blog post rolling around in the back of my head for years regarding how "obviously" is the absolute worst word to use in any kind of technical context. And then go through some of the most egregious things labeled as obvious in various peer reviewed research or blog posts.

I've had a draft for a similar post lying around for a long time too - this would be about the word "just". It's used too often to undervalue work (just a hobby project, just a webapp...) or be misleading about the complexity of things (just set the dns entry, just solve the halting problem).
Post reply on HN