[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Documentation of the private groups proposal



I'm not sure whether the moderation policy is to kill the flamewar by
prohibiting discussion of this issue.  In case it isn't and this
message is approved I shall try to keep myself away from such
inflammatory language and style as I can probably be considered to
have used.

< Thanks. As long as everyone (not just Ian) keeps a moderate tone and the >
< topic is related to Debian, I don't see a problem with the continuation  >
< of this issue. So far, nobody's asked me to squelch this subject, and it >
< would take a lot of complaints for me to do so. - Bruce (Moderator)      >

Bill Mitchell makes some interesting points about documentation.

I agree that documentation is required; a Debian administrators'
supplement would be a very useful (nay, required) document anyway.

I would be more than happy to write or help write such a document.

Also, as I said earlier, several manpages need to be brought up to
speed on the setgid option.  When I have a spare moment I'll submit
some improved ones to Rik Faith.

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'm not the kind of person to dismiss something because it's `just a
documentation issue' - in fact, most of my contributions to the Linux
community have been documentation of one form or another.

What I suppose I was really trying to say was not `oh, that's just
documentation and not important' but more `yes, it needs to be
documented, but don't worry, I'll/we'll take care of it'.

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.

At the moment we don't appear even to have a set of installation
instructions for example - Debian is lacking the documentation that
has to go with a publicly released system.  This is a perfectly
reasonable situation at the moment, but will obviously need work to
correct.

> Any nontraditional umask usage needs to be prominently documented.

Experience I've had on systems which have such a `nontraditional'
umask is that there are no problems even in the absence of any
documentation at all about that arrangement.

Here a paragraph in the FM for adduser and some more detail in the
permissions section in the Debian administrators' supplement will be
enough, I think.

In practice, users neither know nor care, provided that `it works'.

> And if we're going to start UIDs at 1000 (or whatever) we need to explain
> why we did that, explain it well, and and explain it prominently.

Obviously the starting point for UIDs will be documented in adduser(8)
and the administrators' supplement.  However, this doesn't strike me
as a very major issue.

> I'm getting the feeling that it's likely debian will implement something
> in this area in 0.92.  If so, debian 0.92 should include at least half-assed
> documentation of what's been done, of the effects it'll have on sysadmin, and
> of the effects it'll have on Joe User (who won't care) and Jane User (who
> will find it useful once she understands it and understands how to take
> advantage of it).

Again, I think it is a mistake to try to document something that is in
such a state of flux.  If 0.92 is going to be a stable base then
*after* it has been released we can document it.  It's not reasonable
to ask Ian Murdock &co to write all the documentation - they've
already got too much on their plates ...

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.

Ian.
------- End of forwarded message -------



Reply to: