[no subject]
>From pixar.com!debian-devel Mon Mar 28 08:36:02 1994
Return-Path: <debian-devel@pixar.com>
Received: from pixar.com by mongo.pixar.com with smtp
(Smail3.1.28.1 #15) id m0plKIE-0006AIa; Mon, 28 Mar 94 08:36 PST
Received: from mongo.pixar.com by pixar.com with SMTP id AA13736
(5.65c/IDA-1.4.4 for <bruce@pixar.com>); Mon, 28 Mar 1994 08:36:06 -0800
Received: from mongo by mongo.pixar.com with smtp
(Smail3.1.28.1 #15) id m0plKI6-0006AAa; Mon, 28 Mar 94 08:35 PST
Date: Mon, 28 Mar 94 08:35 PST
Message-Id: <9403281634.AA25684@bb29c.mdd.comm.mot.com>
Errors-To: bruce@pixar.com
Reply-To: mitchell@mdd.comm.mot.com
Originator: debian-devel@pixar.com
Sender: debian-devel@pixar.com
Precedence: bulk
Priority: non-urgent
From: mitchell@mdd.comm.mot.com (Bill Mitchell)
To: debian-devel@pixar.com
Subject: Re: Documentation of the private groups proposal
X-Listprocessor-Version: 6.0b -- ListProcessor by Anastasios Kotsikonas
Status: R
This message was submitted by mitchell@mdd.comm.mot.com (Bill Mitchell) to list
debian-devel@pixar.com. If you forward it back to the list, it will be
distributed without the paragraphs above the dashed line. You may edit the
Subject: line and the text of the message before forwarding it back.
If you edit the messages you receive into a digest, you will need to remove
these paragraphs and the dashed line before mailing the result to the list.
Finally, if you need more information from the author of this message, you
should be able to do so by simply replying to this note.
----------------------- Message requiring your approval ----------------------
Sender: mitchell@mdd.comm.mot.com (Bill Mitchell)
Subject: Re: Documentation of the private groups proposal
iwj10@cus.cam.ac.uk (Ian Jackson) said, regarding my remarks re documentation:
>[...]
> I think that perhaps Bill is misinterpreting my attitude, when he says:
> > I know, it's easy to pass this off with a "that's just a
> > documentation issue", and presume that it'll be dealt with later.
I wasn't directing my remarks specifically at anything Ian had said. I
characterized my remarks as drumbeating about documentation, and that's
how they were intended. I've been watching the greate debate on this,
and seen the forces for change gathering momentum. After everyone has
spent so much time and effort arguing their respective points, I just
thought it needed pointing up that it would be inappropriate for the
victorious faction to breathe a sigh of releif and go on to other things
once the issue is decided. Programming is like defecating in that the
job is not completed until the paperwork has been properly done. <<<You
would send this just as I am about to turn off moderation! - Bruce>>> In
this case, the paperwork would seem to involve several documentation issues.
Ian goes on to say
>[...]
> I agree strongly with Bill when he writes:
> > Before debian goes into general non-beta release, the documentation needs
> > to be better than half-assed.
>
> However, there are a couple of things in his message that I want to
> take issue with:
> > ... We need to be documenting it as we are implementing it,
> > not thinking about documenting it; and we should not be releasing it with
> > the special issues in it unless it is accompanied by documentation of the
> > special issues.
>
> That depends on what you mean by `release'. It is very hard for an
> `outsider' to document something that doesn't exist, and it is IMO a
> bad idea to burden those putting together code by saying `thou shalt
> produce documentation for everything'. Therefore the documentation
> has to be written after the fact. This also tends to produce
> documentation that agrees much more closely with the implementation.
>
> The right time to be writing documentation is IMO in the period where
> the beta testers are finding bugs, after the major design issues have
> settled down.
>[...]
> Remember that Debian is still in beta test - to my mind that means
> that only people who don't need the documentation that badly should be
> using it.
I think that this particular case requires some documentation in the
debian release in which shows up. User-notes stuff in a text file
should probably do it for a beta release, provided that the text file
is made conspicuous somehow (perhaps a default motd pointing users to
a README file about the release, and a prominent mention this file in
the release README file, and a pointer to the file for more info).
I recall much argument here about what these changes do and do not do,
what effect they do and do not have, what protections they do and do
not offer, how they are or are not intrusive on unintrested users, and
what an interested user does and does not need to do in order to take
advangage of these changes. I doubt that even those reading all the
debian lists will remember all of that -- much less users who will get a
copy of debian 0.92beta without having seen all the discussions in all
the lists.
Reply to: