request for your comments on release documentation
lists at jnielsen.net
Thu Jun 27 22:17:55 UTC 2013
On Jun 12, 2013, at 11:49 AM, Hiroki Sato <hrs at 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.
> 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.
> 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,
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
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. :)
More information about the freebsd-current