Date: Tue, 22 Jun 1999 01:42:05 -0700 From: Mike Smith <mike@smith.net.au> To: Greg Lehey <grog@lemis.com> Cc: Mike Smith <mike@smith.net.au>, hm@hcs.de, dfr@nlsystems.com, peter@FreeBSD.org, cvs-all@FreeBSD.org, FreeBSD Hackers <hackers@FreeBSD.org> Subject: Re: All this and documentation too? (was: cvs commit: src/sys/isa sio.c) Message-ID: <199906220842.BAA01553@dingo.cdrom.com> In-Reply-To: Your message of "Tue, 22 Jun 1999 18:02:52 %2B0930." <19990622180252.J76907@freebie.lemis.com>
next in thread | previous in thread | raw e-mail | index | archive | help
> And they might, too. phk has frequently expressed a desire to either
> write documentation on existing systems, or at least help others do
> so.
No offence meant, but we can see how much of this has actually
materialised.
> > It has never happened that way (anywhere, on any project),
>
> Of course it has. It's just uncommon in the FreeBSD environment. In
> many large projects, you don't do any code until you have a clear
> definition of what you're going to do.
It's uncommon in _most_ environments. Or perhaps tech writers exist
for some other purpose?
> > and it never will.
>
> My father never had a computer, and his father never did, so I never
> will have one. What an argument.
The circumstances aren't comparable.
> > Documentation is written after the fact, by someone else.
>
> That's the worst kind of documentation. In fact, most UNIX
> documentation is written by the authors. After the fact, admittedly.
In fact, most Unix documentation is never written, being my original
point.
> Hopefully the change of subject line and recipients will get some more
> representative views on this subject.
Perhaps I should have been clearer; the sort of documentation that the
original set of plaintiffs were asking for is the mythical "describe
everything as it was, is and will be, and make it constantly
representative and up to date". These are the same people that will
complain about disparities between any extant documentation and
reality, as well as carp incessantly about the lack of some form
of documentation other than what already exists ("why isn't there a
permuted index?" "where's the sanskrit translation?" "my cat can't read
_this_!").
As always, complaining about the _lack_ of something is the wrong
approach for this project. Step up and fill the gap, or expose
yourself to criticism for failing to do so. There has to be a way to
make a verb from Brett Glass' name, but I'm sure you get the point.
--
\\ The mind's the standard \\ Mike Smith
\\ of the man. \\ msmith@freebsd.org
\\ -- Joseph Merrick \\ msmith@cdrom.com
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe cvs-all" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199906220842.BAA01553>