Update: For anyone interested, we went live with the Aurora notes a couple of weeks ago – https://www.mozilla.org/en-US/mobile/10.0a2/auroranotes/. We’ll be making even more progress towards these goals, over the next cycle. Stay tuned.
There’s been a desire to put out Aurora release notes starting next week. That makes this a fantastic time to rethink the release notes, their audience, and their purpose. For an example of what we’re currently using, you can take a look at the 8.0 beta release notes.
We’ve identified a few issues with the current notes (after the break)
- [content] The two parts of the notes that are most important for a specific release, “What’s New” and “Known Issues”, are hidden behind “+” drop-downs.
- [content] There’s likely too much info on the page, and the info doesn’t appear to be updated as much as link alternatives.
- [audience] It’s unclear who the audience for these notes are, as some of the “Frequently Asked Questions” seem geared towards new Firefox users while the “Troubleshooting” section suggests a user opens up Terminal to debug their issues.
- [audience] Within the “What’s New” section a user who is specifically interested in user features or major bug fixes or new technologies cannot quickly parse the text.
- [implementation] The content of the release notes are currently copy/pasted from one note to another in order to maintain the format and carry over unresolved issues.
- [purpose] The current beta notes do suggest that users provide feedback through input.mozilla.com and Bugzilla, but don’t regularly leverage pre-release users for specific tasks.
The changes we’re currently pursuing are
- [content] We’re redesigning and branding the notes in bug 697337. See that bug for an initial mockup.
- [content] We’ll be culling the number of sections in the notes down to a more manageable set.
- See my proposal for editing in this image (forgive the roughness). Proposed main headings are “What’s New”, “Known Issues”, “Try Firefox”, “Having Problems?”, and “Get Involved”.
- [audience] Non-release channel notes will have different content than our release version – there will be more mention of how testers can utilize engineering tools like Bugzilla (see the last [purpose] bullet).
- [audience] We plan to start categorizing individual items in “What’s New” with tags like “New”, “Changed”, “Fixed”, and other technology-specific tags (think “HTML5″).
- [implementation] We’re going to start maintaining a common data source across all notes (a database of changes/issues).
- See bug 697519 for implementation details. This means we can automatically roll over unresolved bugs from release to release unless they’re marked otherwise. We’ll also be able to query release info and noted issues, which gets interesting in this next bullet.
- [purpose] Because we’re moving to a DB model, when a previously known issue is resolved, all older release notes will automatically link to the Firefox version where that issue was resolved. Value add!
- [purpose] Help curate the bug filing experience for community testers when additional testing is requested through the use of predefined file links.
- For instance “Please consider filing a technical bug report if you run into an issue when using the new animated tab functionality” which basically sets the following parameters automatically
- Product: Firefox
- Component: Tabbed Browser
- Version: 10 Branch
- Comment: “Steps to reproduce your animated tab issue:…”
- (hidden) Keyword: relnote_originated
- That hidden keyword is especially useful in case this experiment fails and teams need to filter out relnote bugs in their triage queries.
If the new notes are considered successful, we plan to roll out similar changes to Beta on the next merge date, and then Release 6 weeks after that. If you’ve got any ideas for making release notes more useful, please share in the comments here or in the bugs listed above. Additionally, if you have any ideas for the best place to source release notes from, or a new process with which Mozillians can propose notes, please share.
