Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Post History

50%
+0 −0
Q&A How can we make compiling release notes less chaotic?

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 ...

posted 7y ago by Monica Cellio‭  ·  last activity 5y ago by System‭

Answer
#3: Attribution notice added by user avatar System‭ · 2019-12-08T03:19:21Z (almost 5 years ago)
Source: https://writers.stackexchange.com/a/29430
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/
#2: Initial revision by (deleted user) · 2019-12-08T03:19:21Z (almost 5 years ago)
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.

#1: Imported from external source by user avatar System‭ · 2017-07-28T23:50:00Z (over 7 years ago)
Original score: 1