Wandering Thoughts archives


Planning ahead in documentation: kind of a war story

I'll start with my tweet:

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

What happened is that we just upgraded our internal self-serve DHCP portal from Ubuntu 10.04 LTS to Ubuntu 14.04 LTS because 10.04 is about to go out of support. After putting the new machine into production last night, we discovered that we'd forgotten one part of how the whole system was supposed to work and so that bit of it didn't work on the new server. Specifically, the part we'd forgotten involved another machine that needed to talk to our DHCP portal; the DHCP portal hostname had changed, and the DHCP portal system wasn't set up to accept requests from the other machine. That we'd forgotten this detail wasn't too surprising, given that the last time we really thought much about the whole collection of systems was probably four years or so ago when we updated it to Ubuntu 10.04.

So what I spent part of today doing was adding commentary to our build instructions that will hopefully serve as a reminder that parts of the overall DHCP portal extend off the machine itself. I also added some commentary about gotchas I'd hit while building and testing the new machine, and some more stuff about how to test the next version. I put all of this into the build instructions because the build instructions are the one single piece of documentation that we're guaranteed to read when we're building the next version.

As it happens, I can make a pretty good prediction of when the next version will be built: somewhat before when Ubuntu 14.04 stops being supported. On Ubuntu's current schedule that will be about a year after Ubuntu 18.04 LTS comes out, ie four years from now (but this time around we might rebuild the machine sooner than 'in a race with the end of support').

Preparing documentation notes for four years in the future may seem optimistic, but this time around it seemed reasonably prudent given our recent experiences. At the least it could avoid future me feeling irritated with my past self for not doing so.

(I'm aware that in some places either systems would hardly last four years without drastic changes or at the least people would move on so it wouldn't really be your problem. Neither are true here, and especially our infrastructure is surprisingly stable.)

sysadmin/DocumentingPlanningAhead written at 01:20:24; Add Comment

Page tools: See As Normal.
Login: Password:
Atom Syndication: Recent Pages, Recent Comments.

This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.