Take the 2-minute tour ×
Writers Stack Exchange is a question and answer site for authors, editors, reviewers, professional writers, and aspiring writers. It's 100% free, no registration required.

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?

share|improve this question

3 Answers 3

The idea of letting the developers write the notes will shatter on the cliff of reality. Most developers don't want to write them, so even if you force them somehow, you will only get a mess and not a note. Just for the record: I am a developer.

What you can do is just improve your existing workflow a little bit. A little bit often does wonders and you will never get a perfect workflow anyway.

Which means, there will always be some back and forth, you already know that. So best workflows are automated, because they skip that damn human factor. Try to automate as much as possible. (Never send a human to do a machine's job.)

  • "annotate with 'affects docs'" - skip that. That's relying on humans and therefore error-prone. I bet you have a priority level on bugs. Define that bugs of the most upper two levels get annotated automatically with "affect docs". Do you really care about the other ones? Developers don't.

  • "Toward the end of the cycle ..." - Ouch! You know what happens if you shift a task at the end of a cycle, so why do you do it? You get the list of relevant bugs now automatically. Have a meeting (a real one, not a lame one) every week, every two weeks, whatever, with the project lead. Go through the list, ask your questions, get answers.

  • "... not sufficiently illuminating" - If things are still unclear (within that one week or two week rhythm) ask the developers. You can never avoid speaking to that lousy pack from time to time. It's a shame.

  • "Iterations happen" - Development is iteration. By its very definition. You'll never get rid of that. Embrace it. It's a cure, not a disease.

share|improve this answer

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.

share|improve this answer

Compiling release notes is NOT the job of a single author. It's ideally part and parcel of your source control and project management system. Your developers would have a set of automated tests for all reported bugs and documented features, and any necessary changes would require a change in said test, which could automatically note a change for the release notes.

  1. New Features would mean new tests, which happily could have supporting documentation. New Test -> New feature added to release notes.
  2. Changes to existing features mean some old tests stopped working. Change a test -> note that "action X and Y no longer does Z."
  3. Bugs, after being recorded internally and having a test written to demonstate the error, can be identified and marked as closed once a "known-bad" test no longer breaks.

Consider, btw, how two games do their release notes.

  • Eve Online does release notes in mammoth lists, introduced by blog posts for major new features and a discussion forum where changes are suggested. Notably, bug fixes are NOT detailed, as there's no public bug repository.
  • Minecraft, on the other hand, has a public bug list and includes links to their actual bug database for resolved fixes.
share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.