request for your comments on release documentation

[Mark Saad]

On Jun 12, 2013, at 5:31 PM, Ben Morrow <ben at morrow.me.uk> wrote:

> Quoth hrs at 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
> 
> ______________________________

Two points. I like the details of the release notes . More detail here is always 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 release and their current  state would be a huge help as well. Say in the case 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 .  

---
Mark saad | mark.saad at longcount.org