Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 23 Jun 1999 08:53:15 +0930
From:      Greg Lehey <grog@lemis.com>
To:        Doug Rabson <dfr@nlsystems.com>
Cc:        Hellmuth Michaelis <hm@hcs.de>, nick.hibma@jrc.it, mike@smith.net.au, peter@FreeBSD.ORG, cvs-all@FreeBSD.ORG, hackers@FreeBSD.ORG
Subject:   Re: All this and documentation too? (was: cvs commit: src/sys/isa sio.c)
Message-ID:  <19990623085315.S76907@freebie.lemis.com>
In-Reply-To: <Pine.BSF.4.05.9906221915000.80685-100000@herring.nlsystems.com>; from Doug Rabson on Tue, Jun 22, 1999 at 07:19:47PM %2B0100
References:  <m10wNKF-0000dCC@hcswork.hcs.de> <Pine.BSF.4.05.9906221915000.80685-100000@herring.nlsystems.com>

next in thread | previous in thread | raw e-mail | index | archive | help
On Tuesday, 22 June 1999 at 19:19:47 +0100, Doug Rabson wrote:
> On Tue, 22 Jun 1999, Hellmuth Michaelis wrote:
>
>>> From the keyboard of Nick Hibma:
>>
>>> And as to the author: Writing docu while you are implementing something
>>> might work in a commercial environment where you want to be able to
>>> market something before it's sell-by date, but for hobbiests who
>>> basically spend the odd evening doing something, it is too much hassle.
>>
>> In case FreeBSD wants to enter commercial environments, we have to behave
>> like behaving in commercial environments.
>>
>> I know that it is current behaviour, much easier and obviously a commonly
>> accepted thing that code, subsystem and/or changes are not and need not
>> to be documented, but this is not a reason in itself for not changing this.
>>
>> Also, i think that the argument Mike and others use: "don't complain for a
>> lack of things, contribute!" - which i use and used all the time - is not
>> valid for this issue: at least i can't contribute because i don't understand
>> things (now someone could argue, that i'm wrong here ...).
>>
>> The last thing i want is a flamewar on this topic and i don't write this
>> because i want to piss onto someones shoes. And i don't write about a
>> man page for "ls" or "more" but a fundamental change in FreeBSD's inner
>> architecture.
>
> Writing software in one's spare time is a case of triage. When I have a
> day or two to spend working on FreeBSD, I have to make a choice on what
> most needs doing and if that is a choice between technical writing or
> designing an algorithm to fix the current limitations of driver detach and
> KLD unload, I don't think the technical writing is going to win.
>
> People must also bear in mind that the most important target release for
> this software is 4.0 which isn't scheduled until next year. I am certain
> that the documentation situation will improve before that release.

Doug, before you get the wrong impression, I don't think anybody's
criticizing you.  My intention was to raise the awareness of the
importance, not of low-level documentation, but of "this is why we did
it this way, and this is how to use it" kind of documentation; much of
it could be in mail messages, but it's stuff which only the authors
can really explain.

Greg
--
See complete headers for address, home page and phone numbers
finger grog@lemis.com for PGP public key


To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-hackers" in the body of the message




Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990623085315.S76907>