Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 23 Jun 1999 08:48:11 +0930
From:      Greg Lehey <grog@lemis.com>
To:        Mike Smith <mike@smith.net.au>
Cc:        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:  <19990623084811.Q76907@freebie.lemis.com>
In-Reply-To: <199906220842.BAA01553@dingo.cdrom.com>; from Mike Smith on Tue, Jun 22, 1999 at 01:42:05AM -0700
References:  <19990622180252.J76907@freebie.lemis.com> <199906220842.BAA01553@dingo.cdrom.com>

next in thread | previous in thread | raw e-mail | index | archive | help
On Tuesday, 22 June 1999 at  1:42:05 -0700, Mike Smith wrote:
>> 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.

None taken.  But if it hasn't happened yet, it's not phk's fault.  The
real problem is a general attitude: UTSL.  Sure, a good hacker can get
by with the source, but good documentation makes for a smoother
project.

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

I don't know too many UNIX tech writers.

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

Why not?  In each case, you're resisting change.

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

That doesn't make it a desirable or unchangeable situation.

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

This clarifies your interpretation of the situation.  In fact, I was
the "original plaintiff", and I wrote:

>> Nice to know there's a man page.  But the real thing is that the
>> "right thing" to do needs to be documented somewhere.  It would be
>> nice, for example, to have an overview of the design principles.  Yes,
>> I know I'm asking for a lot here, but it would really help.

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

I think you're reading more into this than was stated.

> "my cat can't read _this_!").

Put in a PR.  cat should be able to read anything.

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

"To glass"?

Yes, I'm a firm believer in "if it's broke, fix it yourself".  I'm
also not complaining about the current situation; it's probably too
late for that.  But it would be really nice if we could cultivate this
concept of describing what you're doing while you're doing it.

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?19990623084811.Q76907>