June 25, 2003
Release Notes
Talking to Asa yesterday on IRC about 1.4 RC3 made me realize that we need to do something about the release notes. This was confirmed this morning when I found a slashdot comment noting the extreme length of our release notes. Therefore, I present my little 3-step plan for rewriting the release notes:
- Remove the installation instructions from the relnotes. Instead, they belong in a new document (entitled "Installation Instructions" oddly enough) where people can simply select their OS and have installation instructions. System requirements should go here as well.
- The "What's New" and "New Additions to the Release Notes" should go into a README file along with information about other important issues. This should be less than a page long to maximize the chance that someone might read it.
- Lastly, we need to go through the rest of the release notes and remove bugs that have been fixed, minor issues, etc... The release notes are not a known bugs list, that's what Bugzilla is for. The purpose of having release notes is to document specific known issues that are likely to come up in a large number of cases.
And lastly, a bonus idea (4-step plans just don't have the same ring as a 3-step plan):
- mozilla.org/start should (for release builds) display a section at the top of the page containing a "Welcome to Mozilla 1.4 RC3" and then providing links to the README, release notes, etc... For these to be useful, users need to know they exist. While it would be nice to package these in the download, it isn't really possible due to time issues and the face that the relnotes change often. Therefore, linking from the start page is a nice compromise.
NEW! The current thinking is to have a index.html file in the mozilla1.4/ directory containing an index to the other documents:
- installation.html: Installation instructions for mac, win, and linux and links to installation-ports.html
- installation-ports.html: Installation instructions for all port platforms
- installation-extras.html: Extra installation instructions (java, plugins, etc...)
- README: The readme as described above
- known-issues.html: The known issues (formerly the release notes).
Posted by zach at June 25, 2003 11:58 AM
Please make it README.txt and not README for the sake of Windows users' laziness ;-)
README.txt isn't a problem on Linux, its just an extra 3 letters you have to type. On windows it means you can double-click it without changing its name, or choosing "Open With". Since we are trying to convert Windows users from IE, this would be a smart thing to do.
netdemon,
These are all html files, it's readme.html. The relnotes are intended to ship in the mozilla dist, they need to be updated too often for that. These will live in mozilla.org/releases just like the old relnotes.