Why it's good to explicitly document the purposes of things, illustrated

December 9, 2021

Today we decommissioned some internal DNS zones for things that we aren't using or aren't doing any more. Among them were three internal iSCSI zones, which makes sense since we haven't used iSCSI since we moved away from our OmniOS fileservers to our Linux fileservers. But when my co-worker doing the work told me about this, I was surprised that there were three iSCSI networks, since our Solaris and OmniOS fileservers only used two iSCSI networks.

We have a worklog system to record changes and I was able to find the worklog for the addition of the 'iscsi3' iSCSI network, but it didn't have an explanation for what the network was for. Instead it was just written as a matter of fact 'I added this internal zone to DNS' report. Only after a surprising amount of searching our email archives was I able to turn up another entry about a related change that had a brief aside at the bottom that partially explained the intended purpose of this third iSCSI zone. Without that aside, I probably would still be in the dark about the purpose of this mysterious zone.

Broadly speaking, this isn't a surprising new issue for me with our worklog system. I've written about how our worklog messages often assume a bunch of context and how, for example, we lost and regained a piece of Amanda knowledge. But I think this is the first time I've seen us lose track of something as large as the purpose for an entire internal DNS zone (even if we never actually used the zone or really implemented the idea it was for). I'm glad that we sort of documented the 'obvious' (at the time) purpose of the zone in an aside, even if we could have written down the entire thing.

One of the things that this suggests to me is that we should consider sending design documents and other large scale 'what we are doing here' and 'what this is for' documentation to our worklog system, or at least coming up with some way of recording them for posterity. Design documents aren't changes so we don't necessarily naturally write them and send them to our worklog system.

(We do tend to worklog how complicated systems work so we have a reference document that we can search for later, but for other, more 'obvious' things we so far just sort of assume we'll remember the context.)

Written on 09 December 2021.
« Some NVMe drive temperature things from my drives
The question (and some answers) of modern day partition sizes for Linux »

Page tools: View Source, Add Comment.
Search:
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Thu Dec 9 23:24:02 2021
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.