Date: Wed, 12 Jun 2013 17:48:17 -0400 From: Mark Saad <nonesuch@longcount.org> To: "freebsd-stable@FreeBSD.org" <freebsd-stable@FreeBSD.org> Subject: Re: request for your comments on release documentation Message-ID: <69B15075-3CAC-47D4-BCB4-17657A29BA14@longcount.org> In-Reply-To: <20130612213115.GA61462@anubis.morrow.me.uk> References: <20130612213115.GA61462@anubis.morrow.me.uk>
next in thread | previous in thread | raw e-mail | index | archive | help
On Jun 12, 2013, at 5:31 PM, Ben Morrow <ben@morrow.me.uk> wrote: > Quoth hrs@FreeBSD.org: >>=20 >> I would like your comments on release notes for each release. >> Although I have been working on editing them for years, the workflow >> is still not optimal and sometimes delay of the preparation became an >> obstacle for release process. I would like to improve it, but before >> that I would like to know what are desired of the contents which >> people think. >>=20 >> Release Notes is just listing the changes between the two releases. >> It includes user-visible change (bugfix and/or UI change), new >> functionality, and performance improvement. Minor changes such as >> one in kernel internal structure are omitted. I always try to keep >> these series of relnotes items are correct and reasonably >> comprehensive, but this lengthy list may be boring and >> technically-correct descriptions can be cryptic for average users. >=20 > I find the lengthy list extremely valuable. It takes a little time to go > through it carefully, but being able to be reasonably sure nothing > important is missing makes upgrades easier, not harder. >=20 >> So, my questions are: >>=20 >> 1. What do you think about current granularity of the relnotes items? >> Too detailed, good, or too rough? Currently, judgment of what is >> included or not is based on user-visible, new functionality, or >> performance improvement. Applicable changes are included as >> relnotes items even if the changes are small, >=20 > Seems pretty good to me. The only thing I might change is the order: > generally speaking, I'm most interested in the 'User-visible > incompatibilites' section, then in the userland and contrib changes, and > then the kernel changes. The security advisories section is least > useful, because it generally just lists advisories I've already seen and > know have been already fixed; it's a good thing it's there, if only to > make it clear the project takes security seriously, but I might move it > to the end. >=20 >> 2. Do you want technical details? For example, just "disk access >> performance was improved by 50%" or "Feature A has been added. >> This changes the old behavior because ..., and as a result, it >> improves disk access performance by 50%". >=20 > It's interesting, but IMHO only worth it if it's easy. It's not worth > holding a release up for. >=20 >> 3. Is there missing information which should be in the relnotes? >> Probably there are some missing items for each release, but this >> question is one at some abstraction level. Link to commit log and >> diff, detailed description of major incompatible changes, and so >> on. >=20 > The only important additional thing that might be useful would be links > to relevant mailing-list threads in addition to the SVN links. I can see > that might be quite a bit of work to compile, though, so it may not be > possible. >=20 >> Although the other release documentations---Errata, Installation >> Notes, ReadMe, and Hardware Notes---also need some improvements, >> please focus on Release Notes only. And you might think quality of >> English writing are not good, please leave that alone for now. >=20 > There's nothing wrong with your English. >=20 > Ben >=20 > ______________________________ Two points. I like the details of the release notes . More detail here is al= ways welcomed. As a professional FreeBSD SA it helps to have detailed notes.= Second, goes to item 3 noted above: a summary of pr' filed on the previous r= elease and their current state would be a huge help as well. Say in the cas= e of 9.0 to 9.1 it would help if I could read pr's filed about 9.0 that were= fixed / addressed, etc in 9.1 . =20 --- Mark saad | mark.saad@longcount.org
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?69B15075-3CAC-47D4-BCB4-17657A29BA14>