Gregory's Server@Itty53 @benlindsay @hyc @mhoye
The majority of technical documentation I've come across is uber high level and so abstract it loses meaning.
Documentation is getting better, especially when it includes examples so you get an idea of what the high level abstraction actually means.
|
Top-level
10 comments
@berensn @benlindsay @hyc @mhoye And I think examples are fine and great, necessary even, but if that's the only thing you look at in the documentation, that's the problem. Not the documentation. If you're reading a book and don't understand a word, look it up. But you won't get the gist of the book by finding the picture boxes within and just looking at those. Same thing with documentation. @Itty53 @benlindsay @hyc @mhoye I don't need arcanely abstract function documentation, nor do I have the time to pry apart what the documentation authors mean when they write documentation like that. Functional documentation is more useful to a majority of users than high level abstract documentation that is useful only to a minority of users. @Itty53 @benlindsay @hyc @mhoye Calling people not wanting to parse high density abstract documentation isn't lazy, it's using their time on what they deem important. Calling someone lazy for wanting a functional example of how to use a library or function instead of delving into the docs to decode their deep secrets and understand all their aspects reeks of intellectual snobbery. @berensn @benlindsay @hyc @mhoye Yeah no one likes being called lazy but I'll be the first to admit I've had plenty of lazy moments. I AM a lazy person. Consciously aware of that, so I can combat it when it counts. Because of that, my boss though? He'd never think of me as lazy. He doesn't see it. But I know the truth, I am. So I guess you're better than me, since you couldn't possibly be lazy. Right? Not like I'm speaking from decades of development experience or anything. @berensn @benlindsay @hyc @mhoye The problem is you want your example INSTEAD OF. Not along with. You're literally saying you want someone to DO YOUR JOB FOR YOU. That's lazy. I'm not an intellectual snob bro, I'm a lazy person recognizing another one who hasn't yet recognized they too are very lazy, in this case to their own detriment.  @Itty53 @berensn @benlindsay @hyc Demanding industrious and unnecessary work from an arbitrary and unknown number of total strangers because you can't be bothered to write accessible, ergonomically useful documentation and then calling people who balk at that lazy might not be the absolute peak of selfish, self-important entitlement but you're definitely at the last basecamp before the summit. Somebody taught you how to read. You didn't accomplish that with your own hard work. @mhoye @berensn @benlindsay @hyc Yeah dude, we don't agree, and for me that's fine. Doesn't make you evil. But oh, the irony of the ones demanding developers worldwide all get better at explaining things for just the random developer who doesn't want to read more than a paragraph before "understanding", and then calling ME self entitled. Ohhhh that irony. Yeah I was right all along. Old man shouts at clouds. No hard feelings dude. Disagreements are natural. @mhoye @berensn @benlindsay @hyc And I'm gonna point out, your argument of "we're gonna lose a whole generation of developers" could not be farther from true. There's more than ever before, communicating better than ever before. What planet are you living on where this is a dying industry? Your whole argument rests on that bit of falling sky hyperbole and it's literally just not at all true. There's more developers learning out there today than probably all the years past combined. Same docs. @Itty53 @berensn @benlindsay @hyc No, I'm as serious as a heart attack about this, and it's not the same docs. It's sochastically generated approximations of docs, because the real docs aren't effectively meeting real needs. We know, for sure, that you need to be incredibly careful creating example code, because often that example is going straight into prod. But even good examples in otherwise-inaccessible, opaque docs is going to lose out to generated code, and most docs' examples are not. |
@berensn @benlindsay @hyc @mhoye
That speaks more to how often you don't seek out documentation than the state of documentation out there.
Between MDN and MSDN we can say that's close to a majority right there. It isn't too esoteric to use at all. It's just _verbose_. People want example blocks they can copy, not paragraphs of explanation. There's a word for that we all know and can recognize, that's called being lazy. No offense but that's my honest appraisal of the argument.