From owner-freebsd-doc@FreeBSD.ORG Mon Dec 13 17:37:28 2004 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 6DF7916A4E0 for ; Mon, 13 Dec 2004 17:37:28 +0000 (GMT) Received: from mail1.speakeasy.net (mail1.speakeasy.net [216.254.0.201]) by mx1.FreeBSD.org (Postfix) with ESMTP id 3979A43D4C for ; Mon, 13 Dec 2004 17:37:28 +0000 (GMT) (envelope-from lgusenet@be-well.ilk.org) Received: (qmail 17356 invoked from network); 13 Dec 2004 17:37:27 -0000 Received: from dsl092-078-145.bos1.dsl.speakeasy.net (HELO be-well.ilk.org) ([66.92.78.145]) (envelope-sender ) by mail1.speakeasy.net (qmail-ldap-1.03) with SMTP for ; 13 Dec 2004 17:37:27 -0000 Received: by be-well.ilk.org (Postfix, from userid 1147) id 0034644; Mon, 13 Dec 2004 12:37:26 -0500 (EST) Sender: lowell@be-well.ilk.org To: freebsd-doc@freebsd.org References: <20041211145337.GC34046@clan.nothing-going-on.org> <84dead72041212193169c12e38@mail.gmail.com> From: Lowell Gilbert Date: 13 Dec 2004 12:37:26 -0500 In-Reply-To: <84dead72041212193169c12e38@mail.gmail.com> Message-ID: <44k6rm14mh.fsf@be-well.ilk.org> Lines: 44 User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.3 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Subject: Re: Kwalitee X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 13 Dec 2004 17:37:28 -0000 joseph.koshy@gmail.com (Joseph Koshy) writes: > > I'm wondering if we can adopt this idea for the FDP. Can we come up > > I'm wary of metrics as I've seen way too many organizations optimize for the > metric instead of focussing on the real thing. Nik covered this pretty well in his introduction. Since you can't measure the real thing, you need to come up with metrics where naive attempts to improve the metric value would also improve the system. You can't (systematically) improve anything you can't measure. As long as your metric and its first derivative are positively correlated with the results you want, the metric can be useful. > For users: > > Metric: Number of undocumented programs > Rationale: Every program should have a manual page. whatis(1) should > "just work". Well, maybe. Are there many of these that are actually useful to users? > And for programmers trying to use FreeBSD, the following: > > Metric: Number of undocumented APIs > Rationale: Every visible symbol in our libraries should have a description > in a manual page. That's just silly. Functions required by various standards should be documented, and anything of wide use should be documented, but for any function that was intended to be used only by a small number of closely linked modules, forcing people to Read The Source before using the function is a *Good* Thing. > Metric: Number of undocumented kernel APIs > Rationale: Same as above. An appropriate metric might be "number of undocumented kernel APIs whose use has been recommended on the freebsd-questions list this week." But if the suggestion is that documenting the "debug.snapdebug" sysctl would improve FreeBSD, then I think that's silly too.