Date: Thu, 13 Jun 2013 02:49:21 +0900 (JST) From: Hiroki Sato <hrs@FreeBSD.org> To: stable@FreeBSD.org, current@FreeBSD.org Subject: request for your comments on release documentation Message-ID: <20130613.024921.2080910235950489908.hrs@allbsd.org>
next in thread | raw e-mail | index | archive | help
[-- Attachment #1 --]
Hi,
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,
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%".
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.
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.
-- Hiroki
[-- Attachment #2 --]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.13 (FreeBSD)
iEYEABECAAYFAlG4tKEACgkQTyzT2CeTzy3ppwCfTKTsKMD30beEzruRWVAFreAN
HUUAn0aT84nkKyYuLo155V5M0LtPnNto
=b3Ik
-----END PGP SIGNATURE-----
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20130613.024921.2080910235950489908.hrs>