2015-02-11
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.)
ZFS can apparently start NFS fileservice before boot finishes
Here's something that I was surprised to discover the other day: ZFS can start serving things over NFS before the system is fully up. Unfortunately this can have a bad effect because it's possible for this NFS traffic to cause further ZFS traffic in some circumstances.
Since this sounds unbelievable, let me report what I saw first. As
our problem NFS fileserver rebooted, it
stalled reporting 'Reading ZFS config:'. At the same time, our
iSCSI backends reported a high ongoing write volume to one pool's
set of disks and snoop on the fileserver could see active NFS
traffic. ptree reported that what was running at the time was the
'zfs mount -a' that is part of the /system/filesystem/local target.
(I recovered the fileserver from this problem by the simple method
of disconnecting its network interface. This caused nlockmgr to
fail to start, but at least the system was up. ZFS commands like
'zfs list' stalled during this stage; I didn't think to do a df
to capture the actual mounts.)
Although I can't prove it from the source code, I have to assume
that 'zfs mount -a' is enabling NFS access to filesystems as it
mounts them. An alternate explanation is that /etc/dfs/sharetab
had listings for all of the filesystems (ZFS adds them as part of
sharing them over NFS) and this activated NFS service for filesystems
as they appeared. The net effect is about the same.
This is obviously a real issue if you want your system to be fully up and running okay before any NFS fileservice starts. Since apparently some sorts of NFS traffic under some circumstances can stall further ZFS activity, well, this is something you may care about; we certainly do now.
In theory the SMF dependencies say that /network/nfs/server depends on /system/filesystem/local, as well as nlockmgr (which didn't start). In practice, well, how the system actually behaves is the ultimate proof and all I can do is report what I saw. Yes, this is frustrating. That ZFS and SMF together hide so much in black magic is a serious problem that has made me frustrated before. Among other things it means that when something goes odd or wrong you need to be a deep expert to understand what's going on.