@mhoye How are we going to get docs and error messages right when people won't even put version numbers on their Stack Overflow posts?

@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.

@mhoye what…?

@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.

@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?

@mhoye @tante

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).

@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.

@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 Hell yeah!

@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.
I just read a blog post stating that we had no theory of what makes good docs. Come again? There's Information Mapping, Minimalism, EPPO, Funktionsdesign, etc. There are standards, conferences, journals, all about that exact question.
I'm a tech writer myself, and I have never contributed to a FrOSS project mostly because I can't stand the thought of having the same tired discussions there that I already had at work.

@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.
Give me visual programming paradigms; errors that tell you what the hell is wrong; docs with detail AND general information; examples;
Make it fun, not excruciating!

@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

Wheres the mega boost button? Can boost x 10?

@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 Preach, brother! BOFH damaged a generation of devs, convincing them that success meant churning out code and being an asshole with an opinion.

@mhoye there's been a wholeass generation of neckbeards saying RTFM and TFM is SHIT.

@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 Been struggling with Microsoft error messages today. So opaque.

@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 The only true computer worth considering was the EE DEUCE (production version of the ACE) everything else after that was garbage!

@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
man apt-get: apt-get returns zero on normal operation, decimal 100 on error.

Me: (holding slippers) I will send you to Jesus.

@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
> call-and-response glyph-engine supplicancy

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)

173036

@mhoye

@mhoye I mostly got familiar with "tl;dr" as a summary for rants of message boards.

Or did some random service decide to confusingly name itself that?

@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 I hope you know that Unix error messages were — modulo ed — a step up from what came before.

The whole fucking gnu subsystem did not come from that rootstock

@mhoye ah the old days of #VAX #Pascal, developing and maintaining systems with a large cupboard full of useful documentation.

@mhoye I feel as though the PDP-11 is catching strays given that VMS had pretty good documentation.

But I acknowledge that’s egregious nit-picking

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 seldomly have I felt something as much as „call-and-response glyph-engine supplicancy“ in relationship to real programming

@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 I'm curious if there's a correlation between what's considered good versus bad documentation and documentation that was funded and written by professional technical writers versus developers.

@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 Are the original man pages actually bad? One of the distinguishing characteristics I've noticed of everyone who worked at Bell Labs or sort of inherits that lineage (the Go team for example) is their unusually high standard of writing…

@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.
2. With reviews, coaching and prodding, developers can provide documentation that can be used by other developers.
3. Want better docs? Do it yourself.
4. Want really good docs? Hire a technical writer.

@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.