Random thoughts on release documentation

I’ve been doing a few minor updates to the release notes the past week
or two. This isn’t necessarily really exciting stuff (writing the
updates I mean…the stuff they describe really is pretty cool). But I
like doing updates more-or-less as they happen, so I don’t end up
having to do a whole lot of writing during the release cycle.

The other way to approach the release notes is to save everything for
the end. The advantage of doing this is that you can see the context
for everything that happened during the release cycle. The downside,
of course, is that typically things get a little hectic in the stages
of the release. hrs@ prefers this approach, I’ve seen. I think it’s a
matter of preference.

I’ve been thinking of a couple changes I’d like to make to the release
documentation. The main one is to consolidate all of the
machine-dependent (MD) documents, so that there’s only one version of
the release notes (for example) that has annotations to call out
architecture-specific items. Originally I patterned the structure of
the release notes and hardware notes after a couple of text documents
that were maintained separately for the (then) two supported
architectures, i386 and alpha. This doesn’t necessarily scale very
well to the 5-6 architectures we now support!

I writing a quick-start installer guide a year or two ago that
combined all of the MD information; I found it was a lot easier to
edit than the multiple MD documents, mostly because I could print out
a single document with all the text. At some point I’d like to finish
off the quick-start guide, or if that’s not possible, hand it off for
someone else to finish.

So many things to do, so little time…

Speaking of which, I just checked the RE schedule…we’re only about
six weeks away from the start of the 6.2 release cycle!

Leave a Reply

You must be logged in to post a comment.