Re: request for your comments on release documentation

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
>    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