Planning ahead in documentation worked out for us

January 4, 2019

Several years ago I wrote a kind of a war story about planning ahead in documentation, which can be summarized in my tweet from then:

Current status: changing documentation to leave notes for myself that we'll need in three or four years. Yes, this is planning way ahead.

Specifically, I documented various test procedures and additional requirements for our internal self-serve DHCP portal and its overall system. We weren't going to need this information before we updated the DHCP portal from 14.04 (which it became back in 2015) to something else.

Given that Ubuntu 18.04 came out last year and put Ubuntu 14.04 on life support, you can guess the follow-up to that old entry. It's a pretty straightforward one. This fall we updated our DHCP portal from 14.04 to 18.04, more or less on schedule for what we might have expected back in 2015, and when my co-worker did that, apparently my documentation notes from back in 2015 came in handy. So my planning way ahead actually paid off, which doesn't really surprise me but does please me in a quiet little way (since it means that I didn't waste my time back then).

(We missed some things, as always happens, but this time around they were either completely external things or things that were due to the various changes in Ubuntu 18.04. There were also some changes to the overall plans; for example, here in 2018 we've switched from Bind to NSD. We probably didn't have to do that, but we're switching to NSD on all our other machines too.)

One of the reasons that this worked out is that we didn't try to make any fundamental changes in how the DHCP portal worked. Partly we did this because we exist in an environment with long term stability, but another part of it is that we're pretty conservative once we have a system that works. In some other environments, people might have taken this as an opportunity to try something completely new (there's probably some canned 'captive portal' open source software out there, for example). In our environment, we save our energy for other things.

This sort of thing doesn't always pay off, of course. Sometimes our plans or needs change. Who knows what we'll have to do in an IPv6 world, for example. But generally I've been happy with what's come out of planning (way) ahead, and I should probably think about how to do it more.

(Every system here is eventually going to be replaced, and so it's probably worth spending at least a little bit of time thinking about how that might be done and what the obstacles to it might be when putting a new version of the system together. What's going to be a general problem? What little workaround is hopefully not going to be needed in the next version of Ubuntu? And so on.)

Written on 04 January 2019.
« You shouldn't allow Firefox to recommend things to you any more
Some things on ZFS's per-pool performance statistics »

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

Last modified: Fri Jan 4 00:55:21 2019
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.