From owner-freebsd-doc@FreeBSD.ORG  Mon Dec 13 14:29:11 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 884BE16A4CE; Mon, 13 Dec 2004 14:29:11 +0000 (GMT)
Received: from pittgoth.com (14.zlnp1.xdsl.nauticom.net [209.195.149.111])
	by mx1.FreeBSD.org (Postfix) with ESMTP
	id 0B56743D39; Mon, 13 Dec 2004 14:29:11 +0000 (GMT)
	(envelope-from trhodes@FreeBSD.org)
Received: from localhost (64-144-75-100.client.dsl.net [64.144.75.100])
	(authenticated bits=0)
	by pittgoth.com (8.12.10/8.12.10) with ESMTP id iBDET9ag053611
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT);
	Mon, 13 Dec 2004 09:29:10 -0500 (EST)
	(envelope-from trhodes@FreeBSD.org)
Date: Mon, 13 Dec 2004 09:29:10 -0500
From: Tom Rhodes <trhodes@FreeBSD.org>
To: Joseph Koshy <joseph.koshy@gmail.com>
Message-ID: <20041213092910.680170d7@localhost>
In-Reply-To: <84dead72041212193169c12e38@mail.gmail.com>
References: <20041211145337.GC34046@clan.nothing-going-on.org>
	<84dead72041212193169c12e38@mail.gmail.com>
X-Mailer: Sylpheed-Claws 0.9.12b (GTK+ 1.2.10; i386-portbld-freebsd5.3)
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
cc: doc@FreeBSD.org
cc: Nik Clayton <nik@FreeBSD.org>
Subject: Re: Kwalitee
X-BeenThere: freebsd-doc@freebsd.org
X-Mailman-Version: 2.1.1
Precedence: list
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 14:29:11 -0000

On Mon, 13 Dec 2004 09:01:38 +0530
Joseph Koshy <joseph.koshy@gmail.com> wrote:

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

Every utility (your word: program), driver, function.

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

... <INSERT A TON OF UNDOCUMENTED ITEMS IN HANDBOOK> ...
... <INSERT A TON OF OUT OF DATE DOCUMENTATION> ...

-- 
Tom Rhodes