Date: Tue, 22 Jun 1999 21:48:42 +0200 From: Jeroen Ruigrok/Asmodai <asmodai@wxs.nl> To: Doug Rabson <dfr@nlsystems.com> Cc: Hellmuth Michaelis <hm@hcs.de>, nick.hibma@jrc.it, mike@smith.net.au, grog@lemis.com, 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: <19990622214842.D15249@daemon.ninth-circle.org> 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
* Doug Rabson (dfr@nlsystems.com) [990622 20:48]:
> 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 ...).
>
> 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.
I can perfectly understand that, and I like to fill that gap. The gap being
the lack of documentation.
Granted, we can never think of reaching a commercial level on documentating
the internals/code which all the committers provide. To think that is either
dreaming far into the future or just being foolish. However there is a
certain amount of documentation that can be done, skeletal manpages, good
sourcecode comments, and the likes that make filling in the abovementioned
gap easier for those who (are willing and) have the time to do this.
> 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.
It is already getting improved upon Doug.
And as a sidenote, so is asking feedback for pr's what Sheldon is doing a
lot and which I tend to assist him in.
--
Jeroen Ruigrok van der Werven asmodai(at)wxs.nl
The *BSD Programmer's Documentation Project
Network/Security Specialist <http://home.wxs.nl/~asmodai>;
*BSD: We are back and will not accept no...
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?19990622214842.D15249>