Mar 222007

So I got asked yesterday if I’d do the release notes for the impending alpha 3 release of Gecko 1.9. Now, I’m a helpful sort of guy, so I said “yes” even though my memories of doing release notes aren’t pleasant ones (at Be, it took me a week of poring over the bug database to pull together a set of release notes for one OS update).

It’s obviously not nearly has hard when you’re dealing with a relatively monolithic object like Gecko as opposed to the more intricate creation that is an entire operating system along with all its supporting applications. So this hasn’t proved to be so bad.

Still, it’s not exactly my cup of tea either. It’s one of those things people tend to want technical writers to do that I think writers think — or at least, I think ;) — isn’t necessarily the best use of their time.

I suppose it’s something of an edge case. Yeah, it’s writing… I’m just… not sure how technical it is. I’ve always considered release notes to be more of a marketing issue. Sort of a set of bullet points to tell people why they should or should not choose to install a particular update.

For me it tends to turn into an internal debate as to just how much detail is needed. My inherent tendency is to want to document everything quite explicitly, and that’s not really what release notes are for.

Release notes are also a lot easier to do when a project is finished than at some point in the middle. Especially for a writer. You see, as a writer, at present I have only the vaguest idea of where the project stands at this very moment. I don’t really care. My interest lies in where the project’s going to be on the day the documentation needs to be completed. That’s a relatively immobile target to shoot for as a writer (although there are exception cases, where features are pulled or added at the last minute). Right now, I can tell you a fairly decent sketch of what documents will be needed for Firefox 3 and Gecko 1.9.

Conversely, a milestone release, such as the impending Gecko 1.9 Alpha 3, is a very fluid target. As a writer, that makes my life difficult, so I typically prefer to ignore it. While it’s interesting to engineers and testers that Alpha 3 includes support for APNG or includes the new XPCOM cycle collector, from my perspective as a writer that’s only marginally relevant. While it can help me prioritize writing work, it’s not going to absolutely dictate what I do, so it’s not something I generally track closely.

What matters, to me, is ensuring that by the ship date of Firefox 3, everything that needs to be documented is written up as clearly as possible. Documentation doesn’t get written milestone-by-milestone; it gets written with that end goal in mind.

That’s a long-winded way of saying that as a technical writer, having to switch gears and do release notes can be tricky, since I’m having to refocus from the big picture onto a milestone that previously was of relatively low interest.

Of course, someone has to do them, and I’m a helpful sort of guy who likes to be a people-pleaser, so when asked, I take it on, and will do it again if it comes up. I thought I’d share my thought process about my feelings on writing release notes, so there they are.

 Posted by at 4:59 PM

  One Response to “Release notes: a writer’s perspective”

  1. Since you’ve been working on the release notes, please take a look at to see if you can fix it.

This site uses Akismet to reduce spam. Learn how your comment data is processed.