: Re: 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,

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.

Load Full (0)

: Is active or passive voice more common in scientific writing? I am choosing between two sentences: We display the values of X in Table 1. The values of X are displayed in Table 1. The first

@Hamaas631

Load Full 1 Comments

: In contrast to some (or possibly all) of the other answers, I don't think it's to do with what particular traits the villian has so much as whether they embody a consistent set of ideals

@Hamaas631

Load Full 0 Comments

: In searchable documentation, what function does a glossary serve? I work (with a team) on a large documentation set for a complex software product. We publish HTML and have built-in search

@Hamaas631

Load Full 3 Comments

: Examples in documentation can include code, graphics with "fake" data, web sites, and more. Examples are usually tightly coupled with the documentation containing them but often need to be

: Re: 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,

More posts by @Hamaas631

: Is active or passive voice more common in scientific writing? I am choosing between two sentences: We display the values of X in Table 1. The values of X are displayed in Table 1. The first

: In contrast to some (or possibly all) of the other answers, I don't think it's to do with what particular traits the villian has so much as whether they embody a consistent set of ideals

: In searchable documentation, what function does a glossary serve? I work (with a team) on a large documentation set for a complex software product. We publish HTML and have built-in search

: Examples in documentation can include code, graphics with "fake" data, web sites, and more. Examples are usually tightly coupled with the documentation containing them but often need to be

Login to post a comment!

0 Comments

Back to top