From owner-freebsd-stable@FreeBSD.ORG Thu Jun 27 22:17:55 2013 Return-Path: Delivered-To: stable@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 565EE24A; Thu, 27 Jun 2013 22:17:55 +0000 (UTC) (envelope-from lists@jnielsen.net) Received: from ns1.jnielsen.net (secure.freebsdsolutions.net [69.55.234.48]) by mx1.freebsd.org (Postfix) with ESMTP id 24BD31256; Thu, 27 Jun 2013 22:17:54 +0000 (UTC) Received: from [10.10.1.32] (office.betterlinux.com [199.58.199.60]) (authenticated bits=0) by ns1.jnielsen.net (8.14.4/8.14.4) with ESMTP id r5RM0hdJ045017 (version=TLSv1/SSLv3 cipher=AES128-SHA bits=128 verify=NOT); Thu, 27 Jun 2013 18:00:43 -0400 (EDT) (envelope-from lists@jnielsen.net) Content-Type: text/plain; charset=us-ascii Mime-Version: 1.0 (Mac OS X Mail 6.5 \(1508\)) Subject: Re: request for your comments on release documentation From: John Nielsen In-Reply-To: <20130613.024921.2080910235950489908.hrs@allbsd.org> Date: Thu, 27 Jun 2013 16:00:48 -0600 Content-Transfer-Encoding: quoted-printable Message-Id: <65E7FAB6-D6AF-4D97-9379-F10047062734@jnielsen.net> References: <20130613.024921.2080910235950489908.hrs@allbsd.org> To: stable@freebsd.org X-Mailer: Apple Mail (2.1508) X-DCC--Metrics: ns1.jnielsen.net 1102; Body=2 Fuz1=2 Fuz2=2 X-Virus-Scanned: clamav-milter 0.97.5 at ns1.jnielsen.net X-Virus-Status: Clean Cc: current@freebsd.org X-BeenThere: freebsd-stable@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Production branch of FreeBSD source code List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 27 Jun 2013 22:17:55 -0000 On Jun 12, 2013, at 11:49 AM, Hiroki Sato 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