Date: Thu, 27 Jun 2013 16:00:48 -0600 From: John Nielsen <lists@jnielsen.net> To: stable@freebsd.org Cc: current@freebsd.org Subject: Re: request for your comments on release documentation Message-ID: <65E7FAB6-D6AF-4D97-9379-F10047062734@jnielsen.net> In-Reply-To: <20130613.024921.2080910235950489908.hrs@allbsd.org> References: <20130613.024921.2080910235950489908.hrs@allbsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Jun 12, 2013, at 11:49 AM, Hiroki Sato <hrs@FreeBSD.org> wrote: > 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 > 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, I think the current granularity is good. > 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%". I want technical details. You could compromise here by trying to always = have the non-technical end result in the first sentence or so, and then = go on with a more technical explanation. I would echo Mark Felder and say that if in doubt, more detail is = better. > 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. I've not ever noticed any. Thanks! I'm on the SVN mailing lists so I tend to know about or be able to find = changes I care about independent of the release notes. However if there = is a mostly-automated way to link to specific commits in the release = notes that could be valuable. > 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. I've never noticed any language problems in the release notes, and I = tend to be a stickler. :) JN
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?65E7FAB6-D6AF-4D97-9379-F10047062734>