Wandering Thoughts archives

Good technical writing is not characterless and bland

Recently Evan Root left a comment on my entry on a bad Linux kernel message where he said:

I believe the reason why the Yama message is cryptic and 'intriguing' is because tedious committee sanitized messages such as "AppArmor: AppArmor initialized" are at odds with the core principal behind Ubuntu "Linux for human beings"

This is not an uncommon view in some quarters but as it happens I disagree with it. It's my view that there are two things wrong here.

The largest is that clear technical writing doesn't have to be characterless. Good technical writing is alive; it has personality and character. Bland dry technical writing, the kind of writing that has been scrubbed clean of all trace of character or voice by some anodyne committee, is not good writing. You can be informative without boring people to sleep, even in messages like this. In fact, if you look around it's plain that the best technical writing does very much have a voice and is actively talking to you in that voice.

(There is technical writing where you mostly have to scrub the voice out, like technical specifications, but this is because they are very formal and have to be absolutely clear and unambiguous.)

Such writing with personality is of course harder to create than bland dry writing, which is one reason people settle for unobjectionably bland writing. Pretty much anyone can turn that out on demand just by being as boring and literal as possible. But that is not what people should be producing; we should be producing writing that is clear, informative, and has a voice, even if it takes more effort. This is possible.

(This is the same broad school of writing that produces useless code comments that say nothing at great length.)

The smaller thing wrong is that the original message of 'Yama: becoming mindful' cannot be described as a message for human beings (not in the sense that the Ubuntu slogan means it, at least). That is because it is an in-joke and practically by definition in-jokes are not particularly aimed at outsiders. Here the audience for the in-joke is not even 'current Linux users', it is 'kernel developers and other experts'. A relative outsider can, with work and the appropriate general cultural background, decode the in-joke to guess what it means, but that doesn't make it any less of an in-joke.

(And if you do not know what 'Yama' is in the context of the kernel, you will probably be completely lost.)

An in-joke may have character and voice, but it neatly illustrates that merely having character and voice doesn't make writing (or messages) good. The first goal of good writing is to be clear and informative. Then you give it voice.

(This is of course not a new or novel thing in any way; lots of people have been saying this about technical writing for years. I just feel like adding another little brick to the pile.)

A thought on containerization, isolation, and deployment

It started with a series of tweets by C J Silverio:

@ceejbot: maybe this is the cold medicine, but was thinking that containerization is a reaction to a failure of operating systems. Well, unix.
@ceejbot: Or maybe it's a success, because you can do that on top of Unix, but at a cost.
@ceejbot: A app or server or "thing you want to deploy & run" can't be isolated. Config & deps are splattered all over.
@ceejbot: The container solves the problem of "isolate the consequences of installing & running this thing", which is what an OS should do.

My immediate reaction was that one big reason no OS has taken on actually doing this job is that doing it formally requires a huge formalized API.

Think of all of the abstracted things you may need to deploy an application. There's file storage, finding auxiliary files, hooking into (multiple) language environments, process startup and supervision, periodic task execution, logging, network ports, possible creation of separate limited privilege contexts, temporary scratch space, possible permanent writeable space, and so on and so forth. Today all of these are done in ad-hoc ways; you put magic files into magic places in the filesystem and things happen. To make them systematic, to make them formally part of what the OS does, you need to have a formal interface to do all of these things.

(I'm generously assuming that you're basically installing a service, instead of a command or a library or the like.)

There's a lot of things you can want to do for deployment on a general purpose OS. Really, a lot of things. An API that covered all of these things would thus be huge. Designing and building huge APIs is a big problem and they often don't work all that well.

(Regardless of what system they're in and what job they're trying to do. The stories of big APIs for anything are full of failures, perhaps because it's very hard for a coherent big API to emerge from existing practices.)

In this view, containerization is a move that's designed to reduce the size of the API by shifting complexity to inside it. Instead of being able to specify a complex, rich variety of things to do in deployment, you're restricted by the container API to a very small set of options. It's up to you to implement the remaining complexity (or at least its end result) inside the container, using whatever internal API for your own tooling or ad-hoc collection of hacks you like.

(Since currently most people base their containers on some existing Unix, they basically inherit much of the ad-hoc current ways.)

PS: the current ad-hoc magic file locations and so on are of course an implicit API, but from this perspective the two important things are that this implicit API isn't standardized across systems and it's not stable. It may or may not be documented particularly well or completely on any particular system.