Gregory's Server|
15 comments
@Itty53 @benlindsay @hyc @mhoye @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. @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.  @Itty53 @benlindsay @hyc @mhoye "lose a generation of programmers" was not said. "Lose a generation of competency" was said. It means something very different. @paulshryock @benlindsay @hyc @mhoye That's not happening at all either, so whatever I guess? |
@benlindsay @hyc @mhoye
I mean it's as interesting as the other side of the argument, which is "we're going to lose an entire generation of programmers". Which WAS said..
They're both wrong because they're both hyperbole.
That you can find some trash documentation doesn't mean all documentation is trash. That base level error messages generate based on syntax and not human desire is just part of reality.
This whole thread is a giant old man shouts at clouds meme. Sorry to say. 🍿