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!

I’ve found my friends writing recently and it’s such a shame that there is near to nothing on my blog. I’ve just finished minor infrastructure changes to simplify the publishing process for me and I have some ideas for articles. This time, it must happen! I WANT TO WRITE SOMETHING. Keep your fingers crossed for me :)

Free software is a matter of liberty, not price. To understand the concept, you should think of “free” as in “free speech”, not as in “free beer”.

Yes, sure, free software is a matter of liberty, but that doesn’t mean it doesn’t cost anything to create it. Right. Some actual money for the servers and most importantly, for the developers. There is tons of free software out there (and in the broader sense, free content, like Wikipedia) and most of it is a passion project of a well-employed nerd with just a few users, so everything is all right.

So what’s the problem then? Dependability. This model works great if you copy a free picture and use it in your design. If you copy a 25 lines long shell script into your cron. If you grasp the general idea from someone else’s code and use it elsewhere. If you build your work against a tiny library you could, in theory, write yourself, but it would be too annoying (make sure it is in fact tiny, log4j I am staring at you). But things quickly become hairy, if the target is complex and you need to depend on it for 10 years or so. On such a scale the question is not whether a vulnerability will be found, but rather who will fix it. The community? Communities are very powerful. If you’ve ever contributed to nixpkgs, asked in an Arch forum, or otherwise engaged in an active community, you know what I am talking about. They can be very lively, write wikis, answer questions, get their hands dirty and contribute code, but they can never do that alone. Small communities are too small and the large ones need someone to lead them (and the project of course). And these leaders need a ton of enthusiasm (might degrade over time) and/or some money to be able to invest enough time into the project.

Now to the point. Reading articles like this one and nodding in agreement (my free-time occupation for the last 6 years) doesn’t really help. Surely, large companies are at fault, they should pay for the pillars of their success and their money would matter the most, but does that justify regular users paying nothing? No. At least when you can afford it. As a student, I am not exactly bathing in golden coins, but giving the price of a lunch or two a month won’t affect my life in any way. It won’t change the life of the recipient either, but it may send a good message and if I manage to build a habit of regularly contributing and find a good job, I can easily raise the bar. All of the contributions can be found on a dedicated page.

If this way of reasoning sound familiar to you, please join me on a journey to more sustainable open content and be so kind and write me about it. I may list you on this site possibly compete with your donated amounts :).

I recently discovered a useful option — the perimeters count. It is not a magic wand, but just as you start losing hope, it comes to save your day. For certain shapes, it makes the print much more straightforward and therefore much less likely to fail and also much nicer to look at.

Hope it helped someone

The internet is already full of high-quality content, so why make another? Because the world is a complex place with so many variables and pitfalls, so while my posts might not be the most accurate or the most detailed, they might match the situation of the readers and therefore be helpful. I have read many articles showing the obvious, but without them, I would have never realized.