How can we make compiling release notes less chaotic?
Each of our software releases is accompanied by a set of release notes, which include short descriptions of the following: new features, important or breaking changes to old features, and important bug fixes. New features are pretty easy; people know what's happening there. Our challenge is with the other two, which boil down to changes.
The way this document gets compiled now is something like this:
Bugs, when created or anytime thereafter, may or may not be annotated with "affects doc".
Toward the end of the cycle, the assigned writer queries for all those bugs and starts asking around about other things that should be mentioned.
In many cases, the contents of the bug (description or fix) are not sufficiently illuminating to said assigned writer, who then starts asking for clarification from the people involved.
The writer takes his best stab at it and sends a draft out for review. Iterations happen.
Now you can almost never take something directly from the bug because, hey, bugs are written by developers speaking to other developers and aren't meant to be user-facing. A sufficiently technical writer can translate the one into the other, but not all shops have those (and if they do, they're probably writing other documents -- release notes tend to fall to more-junior writers). Many developers could write reasonable blurbs for release notes (these aren't high art), but they need to think of that as a separate task.
So, with all that as background, my question is: how can we improve our workflow to produce decent release notes more easily, with less back-and-forth and less of a scavenger hunt?
2 answers
First off, technical non-writers make better technical writers, than non-technical writers do. They usually can write in a way mostly understandable to layman and factually correct (as opposed to non-technical writers who'll often write something perfectly clear, but completely wrong), they just need to be asked to do so - they won't, if they don't know they should!
Instead of non-technical people assembling the notes, have technical people tasked with assembling them in a relatively reader-friendly manner. Best, if everyone in the team wrote short release notes on everything they did in person, every bug they filed, asked to explain it in relatively non-technical manner (typical to release notes - they know what release notes are). It's 10 minutes of work per month, and you have a good preliminary draft almost complete.
Only then have the non-technical writer edit the draft, making it pretty, correcting errors or smoothing out still too technical language. If something is hard to understand, consult, perform the usual back-and-forth, but the number of these cases should drop to 2-3 per iteration from dozens. Simply, instead of asking the non-technical writers to reach across the chasm to the professionals, have them meet halfway - essentially, everyone becomes the writer, but you're getting one good editor.
This post was sourced from https://writers.stackexchange.com/a/10053. It is licensed under CC BY-SA 3.0.
0 comment threads
I'm at a different company now than I was when I asked this question, but the new one had the release-notes problem too. Here is how we solved it (at doc's instigation):
When a bug is filed, if it's customer-reported or customer-facing, the "needs release note" box is checked. (There is a triage team that reviews these and might change this, but this is the starting point.)
When a developer fixes a bug, if that field is checked he writes a short release note right there in the bug (there's a field for it). Reasoning: he just fixed it; this is the best time to capture what the problem was.
QA reviews/updates the release note as part of bug verification. (Developers sometimes write "internal" descriptions, such as that the problem was with such-and-such mutex being held too long instead of saying that something froze; the testers know what symptoms and changes they're looking for and can verify, so they can fix some of this.)
Near the release, people in doc make a pass over all of them to make sure they're coherent English. (There's a report to find all of them; it's the same report that feeds into the final document.)
Obviously if somebody decides late in the process that that bug needs a release note after all, this breaks down. But for the ones we know will (or probably will) need a release note, we try to capture information as early as possible and improve it as we go along. The incremental cost to the developer at the time of fixing the bug is very low, while the cost for anybody trying to figure it out weeks later is much higher.
0 comment threads
0 comment threads