Gregory's ServerPeople go to Stack Overflow because the docs and error messages are garbage. TLDR exists because the docs and error messages are garbage. People ask ChatGPT for help because the docs and error messages are garbage. We are going to lose a generation of competence and turn programming into call-and-response glyph-engine supplicancy because we let a personality cult that formed around the PDP-11 in the 1970s convince us that it was pure and good that docs and error messages are garbage.
 270 comments
@jelte exactly what I was about to answer when I came here. I've seen entire massive years long enterprise projects with barely any docs. It's the same thing as with tech debt, product people in charge only care about shipping features. And for open source, no one contributes to docs, and the few people making the thing are too busy making the thing   @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. @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.  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.  @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...  @mhoye however bad they are, they exist. People are now used to stack traces and unhandled exceptions as part of a project they consider released, and that’s unforgivable @mhoye It would be nice if both open source and corporate valued the skill that good tech writing entails, and understood that it's a job that requires action with every code change, and understood that it's a different and equally important skill from development. Good docs are gold. (Also automatically generated docstrings and module docs are good but not a replacement for real docs, and auto-synced OpenAPI docs were mostly a pipedream.)  @mhoye Writing and organizing information for discovery and retrieval are both technical (and teachable!) skills that are significantly undervalued by software engineering. In practice, I've find that either companies expect software engineers to do this work incidentally (and, by definition, amateurishly), or if they have a team of writers, they're overworked, disrespected, saddled with terrible tools, and have little access to domain experts. @da_667 @mhoye #Oracle gives precise error codes which help in solving the problem. #Microsoft just gives stupid messages like 'It doesn't work right now. We don't know why (maybe they know but they won't tell you). Try again tomorrow or ask your administrator' - Fuck: I'm the administrator - so whom can I ask !?! 🤯 Unfortunately, many people copy the Microsoft style of error messages 😞  @rkbw @mhoye Yeah, see, thats a place where its an unintuitive mess because Microsoft is fucking awful. But generally speaking, bluescreens have error codes that will at least point you in a general direction for search engine troubleshooting. Additionally the event viewer has become a fallback of mine. Look for Critical failures, Errors, followed by warnings. Again, I fully acknowledge that it sucks and is unintuitive and fully agree that improvements would be effin' great. @IanSudbery @mhoye I refuse to live in a world where willful ignorance of a core function that affects so many peoples' daily lives is accepted. I'm doing what I can to push back. Hows that going for you? Making much headway? I wouldn't have a clue about car maintinance. I chose to learn how to code, rather than how to maintain a car. I can manage to check the tire pressure and if the windcreen washer stops working to fill it up. I'm aware a car must be serviced on a regular basis, and if a warning light comes on, to take it to the mechanic. Who spend their time learning how cars work, rather than how computers work.  @IanSudbery @da_667 @mhoye @IanSudbery @da_667 @mhoye Having read essays by ESR, I do remember how the self-described Unix tribal elder states that documentation that only says things once and expects readers to figure out stuff on their own is good. And this is absolute bullshit. @mhoye @0xabad1dea what kills me is when you do find software with good docs is how few people will read them. Or will see an error and not actually read it and then ask what does it mean? Like what part of “insufficient disk space” was too hard for you to understand?  One of the strong points of paying for Red Hat subscriptions is that there are not that garbage docs  @mhoye Even if the docs and error messages were lovely, they would so rapidly diverge from the fact of the code as to be wrong as a running clock (not even right twice a day, like a stopped clock). @jimfl @mhoye This doesn’t have to be true. If the (reference) documentation strings are part of the source code, and are actively maintained therein by both software engineers and technical writers in collaboration whenever changes are made — and more generally, if providing good, accurate documentation and errors is a considered and intentional aspect of your software architecture — this is eminently possible. @donaldball @mhoye I once had a conversation with a colleague about whether we could enforce this with an automated mechanism. Commits or PRs where code was changed but lacking changes to associated comments would fail. It came down to being able to detect, in any given programming language, which comments were about what code, which seemed like a hard problem. @jimfl @mhoye I have had good success when given the appropriate resources by various combinations of having technical writers flagged via codeowners for e.g. the api contract declarations, having technical writers skim review all changes on a formal release, and providing a clear and actionable grammar style guide so software engineers have a fighting chance to get it right when they write their own. > @jimfl @mhoye whenever practical, use data structures instead of raw code constructs at the documented contract layer Nouns (data structures), verbs (API actions and events), and admonitions (what can go wrong) @mhoye This overlaps with accessibility. If we can't even get basic error messaging or commenting right for decades, I'm sadly not surprised that accessibility is seen as "extra" or "not worth the investment" - because things that are actually HELPFUL TO HUMANS get so easily dismissed. (Also ableism, but... it all compounds.)  @mhoye TBF, the man pages of some UNIX systems are downright awesome (SunOS), even the POSIX standard's man pages read okay. The GNU stuff is quite horrible though. Maybe more of a personality cult around old school UNIX would've been better? :'-) [That being said, stack overflow is quite often crap. And unfortunately there's much incentive to get something "running" without understanding "thing" because that would take a little longer in the short-term.] @mhoye when projects have good docs I shout it from the hills, and even then I have to say, "No, really, I promise, they're good" The number of people in this thread who are willing to tell me that the real problem is how stupid everyone is is incredibly embarrassing. Look, here's what happens when you compile Hello World with single quotes instead of double quotes. Note, please, that these are warnings, not errors. GCC finishes and produces an a.out executable.  Geez, that doesn't look good, but they're just warnings, maybe not deal-breakers. So let's run it and see what happens! An... immediate segmentation fault. Ok, well all those warnings are in printf so let's go look at the manual for printf. https://www.man7.org/linux/man-pages/man3/printf.3.html Oh, yeah, check this out. You can tell we're on the right track: It really gets rolling when we learn about the format of the format string. We wanted to print a string, not a constant character pointer to a "format string", but we can roll with that. "The overall syntax of a conversion specification is: %[$][flags][width][.precision][length modifier]conversion" We're getting warmer you know? You can really feel it. We're close to figuring this out. "The arguments must correspond properly (after type promotion) with the conversion specifier. By default, the arguments are used in the order given, where each '*' (see Field width and Precision below) and each conversion specifier asks for the next argument (and it is an error if insufficiently many arguments are given)." Uh... ok... look maybe we're getting off track here, that first error message said "character constant too long for its type", let's look for that. Let's try something different, maybe gcc --help will do something. And holy shit does it ever.  @mhoye I am currently working on a short tutorial about date-time manipulation in SQLite. I just reached the part where I explain what Julian days are. @mhoye I've been doing a lot in Rust lately. The error messages are ultimately helpful, but can be overwhelming, especially when you start dealing with lifetimes or lambda functions. And I do get that "just learn to read" vibe when I see folks asking for help deciphering them. It's unfortunate. @mhoye All true, but there are some positive examples. On the corporate side, IBM has always been very good about producing complete, accurate, and up-to-date documentation tailored for different audiences - business, end users, technical. In the OSS world, I've found Arch Linux docs to be quite useful. But not everyone takes a professional approach to documentation, unfortunately. @mhoye FWIW, on the Cobol Check project we've always treated documentation as a first-class citizen. https://github.com/openmainframeproject/cobol-check/wiki  I'm quite enjoying every post in this thread. Just popping in to second the motion that Arch Linux are the best at documentation of Gnu - I mostly run Debian and its derivatives, but I frequently go to Arch's docs first.  @mhoye this is because engineers these days strongly resist writing documentation and insist the code documents itself so what's the point? I expect another recent trend will be an engineer asked to write docs will just ask their favorite GPT plugin to do it. As we know that's a hit and miss activity depending on what hallucinations AI is on that day. @mhoye Part is the arrogance in tech towards docs as a valid domain on its own. @mhoye To the folks that say the real problem is people are illiterate and stupid, i say, no, the language is deliberately obscure because it was designed in a time of computational and user interface constraints. Now we have abundance, and I'm supposed to remember what the magic words mean? No thanks.  @mhoye programming books and how-tos should always be simple enough that a middle-schooler can understand them. the complexity should be in the actual content, not in deciphering what on earth those terse explanations even mean. there’s absolutely no reason to make the easy parts intentionally harder than they are just to make the hard parts seem cooler   @mhoye I don't think that's quite where to place the blame. Old UNIX culture always demanded man pages for binaries _and_ library calls. It's the modern web that treats it with contempt, which is why there is, for instance, no manual for YouTube, or GMail, or or Android. Google is a big driver of the obnoxious no-documentation culture. @mhoye this. So very much this. The amount of programs with error messages like "an error occured" or just "error". And the amount of projects where you search for docs. And all you get is blogs on one very small use case (i.e. how to do NAT with nftables, good luck finding docs on anything else). Then some fucking numpty decides that they should name their tool with a dictionary word. Linux replaced brctl with bridge. Googling for help with bridge just gives brctl results.  @mhoye there seems to be a lot of room for more interactive documentation, where the user can build intuitive understanding through simple, visual explanations. For example, https://regex101.com I've been prototyping a CLI app documentation explorer in this style that breaks down commands/arguments with visualisations and examples. It's very simple, but the improvement over a wall of text seems pretty clear to me. Just a shame this kind of thing doesn't already exist. @mhoye and i can tell you ChatGPT steals the stuff from Stack Overflow I saw it from my own eyes exactly the same snippet of code in ChatGPT and Stack Overflow otherwise ChatGPT has zero ability to think for itself.. Its more or less a procedural generation algorithm it cannot do any type of logic. @mhoye spicy take but you really have the history down. Yeah it is not a coincidence that I love nodeJS, despite somewhat high inherent complexity, because it has such ferocious API consistency and decent documentation.  @mhoye It’s true. Also, even assuming the docs are good, I need to do something I don’t know how to do, or I encounter an error. Do I go to the language or software web site, assuming I remember the domain or bookmarked it, search where they buried the link to the docs, use the web site’s shitty TOC or shitty search function to find the page that addresses my problem? >> @mhoye can I just be a jerk and say that “it depends on the software” ? I mean, people tell me that “if I google an issue about #OpenBSD, I can't find answers, why is that? is it a dead project and no one uses it?" And I have to explain to them that “No, the docs are SO GOOD that people don't need to ask questions online and answer them. They just read the docs" So I agree with you, error messages and docs are garbage, but not for everything. However, completely true of GNU :P @mhoye this is a huge problem and turns onboarding into a nightmare. it's why a senior dev's productivity will likely go down for a while when a new hire is brought on. but i also see "documentation" repeatedly get glossed over in SDLC as "it's just part of writing the code". it isn't part of the code; it deserves and needs dedicated time. it should be mutually exclusive with writing code, but not lumped in as one. Hilarious rant, @mhoye! This is indeed the world we live in! Oh, and you should have grepped the compiler source for the warning messages you got XD  @mhoye@mastodon.social  @mhoye It's less folks being unwilling to document, and more people not being able to get paid to write good documentation and errors. Writing high-quality documentation and error messages is hard. Very hard. But getting your boss to agree to let you spend time on them is harder. @mhoye I agree with you, but that sounds wicked.  @mhoye alternatively folks can give me money and i will give them docs (and error messages?) that are good  @mhoye having used PDP-11s, though in the 80s, this was all utter bullshit then, too, and inexcusable. Some operating systems and languages had actual good docs and help, but Unix and C were not amongst them. And it was stupid. (I remember the first time I tried to use C, on a PDP-11 even, and gave up because the docs were such crap)  @mhoye I’m a cybersecurity analyst and not a tech writer because I could get paid to do it. Tech writing? Anyone can write and use Word, why would we pay well for that? I went from making 45k to 95k with the same skill set. That was 15 years ago.  @mhoye and the fact that SO helps them shows that it is possible to write down what people want and need to know in a way they can use. It is not a reading comprehension issue, it's a writing ability issue.
documentation, folks. The best engineered software in the world is *nothing* if it isn't documented clearly and in-depth  @mhoye I wrote my own stack VM and compiler for a laugh recently and literally the first thing I did after getting it into a basic working state was give it really nice error messages with suggestions of how to fix the issue if you make a mistake, because I was gonna be hacking at this thing for weeks and knew I'd need decent feedback to catch my sleep-deprived keyboard snafus. srsly, compiler devs, do it for your own sanity as much as anyone else's.  @mhoye I've been saying this for decades. The problem starts with: #define EPERM 1 /* Operation not permitted */ What operation? On what object? Due to what context or user identity? Who do have to ask for permission? Continues: #define ENOENT 2 /* No such file or directory */ Is it a file or a directory? Which part of my pathname failed? Is it because a directory isn't searchable or just doesn't exist? The operating system clearly knew all these facts, but returned only -1 and an errno @mhoye ACK. Saying similar for years. I was sitting in front of a problem some time ago, was reading the docu and after hours didn't find out what the hell the dev was meaning. I asked in the IRC channel for help and then two devs started to point on different chapters in the docu and yelling on each other, until I found a stack overflow where a linux engineer said "the docu was shit, the solution is something else" and it worked. @mhoye It is the 41st millennium. 1,000 SREs per day are sacrificed to the golden throne of Kubernetes. @mhoye I only partially agree with you. I personally think that most of the time people are lazy. They don't like to RTFMs. Just this! They don't want to learn, they want answers, immediate answers and solutions to whatever question/problem they have. That's why LLMs are being so successful. @mhoye Web development is not so bad now that Internet Explorer is dead   @mhoye agreed generally, but Go has good error messages, so it can't be as simple as "personality cult that formed around the PDP-11 in the 1970s convince us that it was pure and good that docs and error messages are garbage", can it? I remember seeing Russ Cox get raked over the coals once in a discussion when someone asked/complained about (a) knowing that something that worked in C wouldn't work in Go but (b) not knowing how to actually do that thing in Go. 1/2  @mhoye openbsd man page are so good, they put them all on the web. http://man.openbsd.org have like all their manpage ever wrote  @mhoye This is a first-class rant, and I agree entirely. While I´m not a developer, a large part of my job is translating between techies and everyone else (management, sales, customers, you name it). My experience is: 1. Developers will write the documentation they themselves need. @mhoye I completely agree with this position. And I think @melix , which wrote a very fluent and nice error management library (which tried to avoid as much as possible the garbage side) - https://github.com/melix/jdoctor  @mhoye very true. I often find that reading a library's source code is way easier than trying to find information I'm looking for in their documentation or error messages. |
@mhoye Nobody pays for docs and error messages.