|
Top-level
 @mhoye TLDR exists because people are illiterate and stupid. People ask chatGPT for help because they're illiterate and stupid. The people building chatGPT used the same software tools as everyone else. If docs and error messages were all garbage then nobody would ever be succeeding at any software projects. 66 comments
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. 🍿 @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. @jrconlin @mhoye there's definitely a difference between a technical reference manual and a user guide. General function belongs in the latter. But by its very nature, it's going to be lengthy, particularly if a lot of basic concepts need to be introduced. Complaining "tl;dr" is bogus if the necessary information is present and concisely delivered.  If you're telling people that the solution to navigating bad documentation is to learn regular expressions, then I don't even know what to say. That's like telling somebody who's struggling to climb a mountain that why don't you just learn how to fly? Anyway, here's what you get when you use gcc to compile Hello World, with single quotes instead of double quotes. Not, please: those are warnings, not errors. The compile actually finishes and produces an executable. @mhoye I'm not sure what you're trying to illustrate with that example. You seem to be suggesting that compilers should be friendly enough to be usable by people who don't know the programming language. A C programmer has to know the difference between a character constant and a string literal, and what a multicharacter constant is. It's not the tool's job to teach the language syntax.  @a @mhoye The tool can't read the programmer's mind. Perhaps the "not a string literal" message should have been an error instead of a warning, since it clearly doesn't conform to the function signature. But beyond that, the programmer should know the difference between a string literal and any other data type. That's basic knowledge of the language. Knowing printf's signature is too, that's part of the language spec.  Ancient Sumerian is the oldest form of written language, and there are numerous translation texts available. Surely, it's no challenge to the modern reader. To presume that someone has skill or knowledge is to exclude a large number of people. Everyone has their own skill sets. Your skills are not as important to others. True, but you're also far more likely to find someone translate from French than Sumerian. Thus why we now have TL;DR and Stack Overflow. If I found out more people read someone else's summary of a tool or library that I wrote, I'd do my best to work that summary in as my documentation. Maybe even take a few pointers about how to present information better as well. Uhm, maybe they wrote it because they don't understand how to submit a PR? (Again, different skill sets and not wanting to learn Sumerian. That's why requiring knowledge from someone can make your life harder.) Maybe just reaching out to them would be enough, and a courteous thing to do anyway so that they get proper credit? Heck, even if they say "No", there are still lessons to be learned. @jrconlin @mhoye not everything revolves around github PRs. A simple email "hey I wrote this summary for you" is all it would take to get the ball rolling. Putting the onus on the developer to reach out to the user for this is unsustainable and unrealistic. It would require constantly sifting the web to find these useful snippets. Whoever wrote the summary just has to hit Send on one email. Heh, and all the original doc writer had to do was get one editor. Which is pretty common and not difficult at all for any professional writer. Asking the audience to do that for him is unsustainable and unrealistic. The author wrote that up because they don't believe that the original source sufficiently solved their problem, nor would the be able to. Kinda damning, if you think about it. @jrconlin @mhoye so now you seem to be demanding that developers be professional writers. I suppose it's fair to expect professional writers to be employed by commercial software providers. Not fair to demand anything of open source; if no one steps up and volunteers then the audience has no one to blame but themselves. I'm asking that developers be aware of skills that may not be code based, yes.  @jrconlin @hyc @mhoye the solution to "there is a big gap between what maintainers provide and what users need" is not to ask overworked/underpaid FOSS maintainers to take on more responsibility. nor is it to deny the need exists. the solution is for the broader community to recognize the value of user-facing, newcomer-friendly docs and dedicated user support, and to help maintainers provide them. that requires investment. it's part of the broader open source collective action problem.  I think it's also somewhat important to note scale. A tiny package used by a few folk probably doesn't need much more than what folk already do. This would probably not overburden that one guy in Nebraska. Once a project "graduates", takes on devs, and grows in use, then documentation becomes more important, just like security updates. Large projects should help by reaching down to smaller ones that they depend on. It would be more appropriate if you stopped asking and started doing, at least in the context of open source. The developers of any OS software have exactly zero obligation to fulfill random wishes of random dudes who happened to find their software useful. If you want to get it done, do it yourself or pay somebody to do it instead of wasting time to whine about it on the public internet instead of using a bug tracker. My dude you have gone from "the problem is that people are stupid and illiterate" past "just learn regexes" straight to "asking developers to be competent at communicating in writing is bad", and you can fuck right off with all of that. You don't want to write docs, we get it. Just own the fact that you'd rather sneer at people than rub two synapses together to think about usability and leave it at that. @mhoye @jrconlin people write open source code because they saw a need and decided to address it. The fact that tech writers haven't also seen a similar need and stepped up to address it isn't the open source devs' fault. Demanding that someone who gave you a gift give it to you in a particular shape, size, and color is just being greedy. @mhoye @jrconlin to accuse me personally of not wanting to write docs is baseless. My LMDB project is thoroughly documented. Not only are the docs complete and easily accessible http://www.lmdb.tech/doc they're written in Doxygen, embedded in the source code and header files and always kept up to date with code changes. I feel like we're closing the circle here. I know that I am not a good enough writer or editor to presume that my docs are perfect. I also don't presume my audience is lazy or stupid. It also presumes that there is only one logical path for information to take, when that's seldom the case. It's also why books have tables of contents and indexes. (I'll also note that the most popular track on that album comes fifth, and it's not like folk are always listening to everything that comes before it.)  @hyc no, people prefer TLDR and chatGPT because they need to get something done in a timely manner and don't have a free hour(s) to sort through poorly worded, often outdated documentation. @hyc @mhoye Even if we accept your premise ("people are illiterate and stupid"), in a world where more and more people are going to need to code to keep the world going, we are going to need to create systems that work for these "illiterate and stupid" people. We can't just fix the world by declaring that from now on all people shall be geniuses.  "Illiterate and stupid" seems like a bold take of victim blaming for the various engineers that are trying to learn how to build and use tools, but have not been provided with sufficiently clear and accessible documentation that meets their needs...  @hugh considering I never said anything about perfect knowledge, you've done an admirable job of illustrating the point that people don't read. @jimgar @mhoye I mean that you would have to be a moron to rely on chatGPT for help writing code. LLMs don't understand the data they're working with, they're just pattern matching text. I mean that if you say "tl;dr" before even reading the docs then you're in no position to judge whether the docs are good or bad. https://mastodon.social/@jonny@neuromatch.social/111326985064873191 @jimgar @mhoye chatGPT is just ELIZA with a larger database. https://mastodon.social/@hyc/109455112129583944 |
Gregory's Server
@hyc @mhoye "Things happened therefore they couldn't have happened any better" is an interesting stance to take