From owner-freebsd-doc@FreeBSD.ORG  Mon Dec 13 03:31:40 2004
Return-Path: <owner-freebsd-doc@FreeBSD.ORG>
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 0F6FE16A4CF
	for <doc@freebsd.org>; Mon, 13 Dec 2004 03:31:40 +0000 (GMT)
Received: from rproxy.gmail.com (rproxy.gmail.com [64.233.170.199])
	by mx1.FreeBSD.org (Postfix) with ESMTP id A52B343D41
	for <doc@freebsd.org>; Mon, 13 Dec 2004 03:31:39 +0000 (GMT)
	(envelope-from joseph.koshy@gmail.com)
Received: by rproxy.gmail.com with SMTP id z35so606058rne
        for <doc@freebsd.org>; Sun, 12 Dec 2004 19:31:38 -0800 (PST)
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws;
	s=beta; d=gmail.com;
	h=received:message-id:date:from:reply-to:to:subject:cc:in-reply-to:mime-version:content-type:content-transfer-encoding:references;
	b=GQaPgSbok4h0qRYYfTXNAdS2HUFrz4+r99VGCONKq1Jxpglh75/5dyu8ytrrl38hgwyH7Fh7FPX1+fIaIeWSjbmVo4D02izwfCV3SsqdVAAr1FgVVa+0rbDMYTRkzwE/WwQ99WpaDzdlsBsr08YbscYiCL5nlRFqx4YHrRhM2/g=
Received: by 10.38.97.8 with SMTP id u8mr1154662rnb;
        Sun, 12 Dec 2004 19:31:38 -0800 (PST)
Received: by 10.38.209.11 with HTTP; Sun, 12 Dec 2004 19:31:38 -0800 (PST)
Message-ID: <84dead72041212193169c12e38@mail.gmail.com>
Date: Mon, 13 Dec 2004 09:01:38 +0530
From: Joseph Koshy <joseph.koshy@gmail.com>
To: Nik Clayton <nik@freebsd.org>
In-Reply-To: <20041211145337.GC34046@clan.nothing-going-on.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
References: <20041211145337.GC34046@clan.nothing-going-on.org>
cc: doc@freebsd.org
Subject: Re: Kwalitee
X-BeenThere: freebsd-doc@freebsd.org
X-Mailman-Version: 2.1.1
Precedence: list
Reply-To: Joseph Koshy <joseph.koshy@gmail.com>
List-Id: Documentation project <freebsd-doc.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
	<mailto:freebsd-doc-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-doc>
List-Post: <mailto:freebsd-doc@freebsd.org>
List-Help: <mailto:freebsd-doc-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
	<mailto:freebsd-doc-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Mon, 13 Dec 2004 03:31:40 -0000

Nik,

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

That said, it would be cool to have a web page where we could look up the
current 'kwalitee' of our documentation.

> So to kick off, some metrics we might use, and the rationale behind
> them.  It should be possible to mechanically check each metric.

I like all of these.

Here are some more suggestions:

For users:

Metric:       Number of undocumented programs
Rationale:  Every program should have a manual page.  whatis(1) should
                  "just work".

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.

Metric:       Number of undocumented kernel APIs
Rationale:  Same as above.

The intent for these two is to make FreeBSD a nice platform to develop on.