From owner-freebsd-questions@FreeBSD.ORG  Fri Dec 30 16:03:41 2011
Return-Path: <owner-freebsd-questions@FreeBSD.ORG>
Delivered-To: freebsd-questions@freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id EDAFD106564A
	for <freebsd-questions@freebsd.org>;
	Fri, 30 Dec 2011 16:03:41 +0000 (UTC)
	(envelope-from freebsd@edvax.de)
Received: from mx01.qsc.de (mx01.qsc.de [213.148.129.14])
	by mx1.freebsd.org (Postfix) with ESMTP id A9F198FC0C
	for <freebsd-questions@freebsd.org>;
	Fri, 30 Dec 2011 16:03:41 +0000 (UTC)
Received: from r56.edvax.de (port-92-195-26-82.dynamic.qsc.de [92.195.26.82])
	by mx01.qsc.de (Postfix) with ESMTP id 36B513CC1D;
	Fri, 30 Dec 2011 17:03:40 +0100 (CET)
Received: from r56.edvax.de (localhost [127.0.0.1])
	by r56.edvax.de (8.14.5/8.14.5) with SMTP id pBUG3dm0002043;
	Fri, 30 Dec 2011 17:03:39 +0100 (CET)
	(envelope-from freebsd@edvax.de)
Date: Fri, 30 Dec 2011 17:03:39 +0100
From: Polytropon <freebsd@edvax.de>
To: David Jackson <djackson452@gmail.com>
Message-Id: <20111230170339.6d6af931.freebsd@edvax.de>
In-Reply-To: <CAGy-+i-m7hUfrUPKaG6FAiv8cor6+WXUW-OwWA=uOAt0yDToag@mail.gmail.com>
References: <CAGy-+i-NN_SOYrrE6WgHyCBa5VzFexwT_C9UYhO3GyjvfsxpAA@mail.gmail.com>
	<201112300604.pBU64dqB069626@mail.r-bonomi.com>
	<CAGy-+i-m7hUfrUPKaG6FAiv8cor6+WXUW-OwWA=uOAt0yDToag@mail.gmail.com>
Organization: EDVAX
X-Mailer: Sylpheed 3.1.1 (GTK+ 2.24.5; i386-portbld-freebsd8.2)
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Cc: freebsd-questions@freebsd.org, Robert Bonomi <bonomi@mail.r-bonomi.com>
Subject: Re: FreeBSD Kernel Internals Documentation
X-BeenThere: freebsd-questions@freebsd.org
X-Mailman-Version: 2.1.5
Precedence: list
Reply-To: Polytropon <freebsd@edvax.de>
List-Id: User questions <freebsd-questions.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-questions>, 
	<mailto:freebsd-questions-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-questions>
List-Post: <mailto:freebsd-questions@freebsd.org>
List-Help: <mailto:freebsd-questions-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-questions>, 
	<mailto:freebsd-questions-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Fri, 30 Dec 2011 16:03:42 -0000

On Fri, 30 Dec 2011 10:22:31 -0500, David Jackson wrote:
> Of course, those best able to document are those who wrote it in
> the first place, since they already know how it works.

A fact seems to be: "Modern" programmers don't bother
with documenting, or coding guidelines, or style or
other things that "slow down" development. This
attitude isn't new in general, as it has been done
that way even in IT dinosaur times: There are COBOL
programs still running, and nobody knows _why_ they
are running and _how_. If someone had written usable
documentation at the time the program was created
and maintained, skilled COBOL h4x0rs wouldn't be
able to write the desired salary on the contract
as _they_ wish. :-)

But keep in mind: Writing code and writing documentation
are two different things. There are people who are
excellent coders, but bad writers. In some teams,
you'll find code writers and doc writers separated,
but working together. This approach isn't free of
problems, but also seems to work.


-- 
Polytropon
Magdeburg, Germany
Happy FreeBSD user since 4.0
Andra moi ennepe, Mousa, ...