Post History

Source: https://writers.stackexchange.com/q/10052
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

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?

Original score: 6