Date: Wed, 12 Jun 2013 22:31:19 +0100 From: Ben Morrow <ben@morrow.me.uk> To: freebsd-stable@FreeBSD.org Subject: Re: request for your comments on release documentation Message-ID: <20130612213115.GA61462@anubis.morrow.me.uk> In-Reply-To: <20130613.024921.2080910235950489908.hrs__24811.884322162$1371059499$gmane$org@allbsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Quoth hrs@FreeBSD.org: > > 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. > > 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. 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. > So, my questions are: > > 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, 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. > 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%". It's interesting, but IMHO only worth it if it's easy. It's not worth holding a release up for. > 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. 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. > 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. There's nothing wrong with your English. Ben
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20130612213115.GA61462>