Give back useful documentation

Just dumping a quick mental meltdown here: Please, pretty please, can we go back to good old boring developers documentation style? I mean those terse articles presenting real new information? Those long walls of text that nobody ever wants to read, but ends up reading because they contain what one is looking for?

It doesn’t have to be so bad. There are well-written documentations that are a pleasure to read, but the core point is that they have to actually convey some facts. It might have just been a bad month for me, but I was confronted with too much screwed-up docs and I think it hadn’t been so bad in the past. I am afraid it is an inevitable consequence of replacing real humans with LLMs or simple machine generated garbage. Both of the recent instances were from Google, but I meet it just everywhere. The docs tell the obvious (“To assemble a car, you gotta get a wrench from your box. Beware there are two latches, if you only press one, the box won’t open preventing you from obtaining the wrench”) and pretend the rest is intuitive (which it often sort of is) ignoring the parts where one can honestly need to tweak some details (“Then put all parts where they fit. And if you get lost, ask our chat bot”).

The first one was the YouTube API. I remember (though it can be just dreamed up) seeing Google’s API reference in reasonably good shape in the past, but this time, it was all just

This JSON attribute named x contains x

with little additional description of the semantics. And if you then mess up different id attributes because you think it’s a video that you are handling but it’s a playlist item instead (I admit it was my mistake), the API greets you with a pretty useful 403. And yes, thanks for asking, the semantics of the error codes are documented, except 403 isn’t and 404 is guaranteed anyway. ❤

And then I was forced to interact with their serverless functions we’ve been using for quite a fer years. They unobtrusively presented that Go’s 1.21 runtime is about to be deprecated and later removed so it might be a time for upgrade. For far so good, it is a reasonable decision with a rather generous time schedule. I do a few clicks at the web interface and ha! I can’t select a never runtime, 1.21 is the only available one. Can it be related to them deprecating the whole v1 cloud functions stack hoping to push us to v2? That must be documented somewhere, right? We can easily find either a deprecation notice or generally some info on the future of v1 functions or at least find the list of supported execution environments of v1, right? Nope. They beautifully retrospectively renamed Google Cloud Function to Cloud Run Functions v1 (probably dropping the original Cloud Run product (or just rebranding it is v2? 🤷)) and merged its documentation with v2. They are supposed to be very much compatible, so why bother? Links explicitly marked as documenting v1 point to some shared docs crossroad where you can again pick you are interested in v1 to get to a short page again pointing you to some v2 resources, pointing you to how to deploy v1 code and how v1 compares to v2 (of course they just claim it is sort of compatible with no technical details).

I thought “Game’s not over. We’re actually using Firebase, so we can try their docs?”. I was so naive. They are the other extreme I was writing about in the preface: they contain just a lot of examples, but no real information. It’s always good to show the audience how to accomplish the most frequent tasks and give them some confidence if the sole theory is too dense. But you can’t skip the theory! Defining your config format by a collection of snippets is just bullshit even if it is clear how they actually compose together.

Alright, I’ve probably calmed down by now. Enough ranting, back to useful work. Take this post with a grain of salt as wasting multiple hours on that YouTube HTTP 403 really turned me mad, but I really feel like the best current documentation is usually in the man pages these days. I wish they covered everything out there. Of course it isn’t about source format, it’s about the style. Boring and terse but always with a preface with motivation and high-level, detailed list of whatever is to be listed, additional sections with security considerations etc and finally a bit of examples both the simple and more convoluted ones. If you feel it the same or on contrary very much disagree (and everything in between), make sure to share your thoughts!

If you’re reading this and are responsible for a public facing documentation, hear me: it is nice to provide an AI assistant, but keep in mind it can’t understand your product if you don’t have it written down. LLMs shine at summarizing text and extracting pieces of information on request (“What’s the name of the function that does this and that?”) and it can really save one’s time. It can probably also generate all those usage examples, so please stop concentrating on what can be automated. Provide us with genuine list of facts and an architectonic overview with forward-references. We can then synthesize what we want with our little brains or use some digital ones if we want to. Thanks!