Re: Notes for DDP writers
On 14 Feb 1999, Adam Di Carlo wrote:
>
> I'm sorry, but I'm going to have to *strenuously object* to the mere
> existance of these manuals.
>
> For one, 90% of the contents of these manuals are Linux-specific and
> not Debian specific. As such, to undertake these manuals as *Debian*
> manuals is contrary to the ideals of the Free Software Movement --
> sharing and the greatest benefit to all. I happen to know a *number*
> of quality Linux documentation folks who have taken issue (quietly)
> with the existance of these manuals.
>
> I really think this is important. Debian manuals should be about
> Debian. Linux manuals should be worked on by groups which are not
> just restricted to the Debian group.
>
I am saddened to hear that people are upset about it. I did contact the
LDP when I started on the tutorial, exchanged some mail with the author of
the LDP User's Guide, etc. I've also talked to RMS about it. Basically
made every effort to work with non-Debian people.
If I remember correctly, the LDP User's Guide guy (Larry Greenfield, IIRC)
said he wasn't actively maintaining things, but he could send me
backlogged contributions to the User's Guide. I ended up working from the
User's Guide, which needed/needs updating and distribution-specific
information. Larry's work was very helpful to me.
Now, I can't get all high-horses about it, because I've run off and spent
all my time hacking Gnome, gnome-apt, etc. instead of finishing the
manual; and the manual has languished and I don't even know when I'll get
back to it. But I do think an effort was made to talk to and work with
existing projects. So if people are upset, they should contact me (or us)
instead of sulking.
I would have no objection to adding #ifdef type things to the manual with
Red Hat specifics, or some other approach. But no one is volunteering to
do the work. (Perhaps that's why they're sulking, rather than contacting
me.)
(More would change in a non-Debian tutorial than you might think; many of
the examples would break and be impossible to do "portably"; all the
political stuff at the beginning, which I consider important, would have
to go; config files are in totally different places; package management is
totally different. It really is a _Debian_ Tutorial, it is not a Linux or
Unix tutorial that gratuitously says Debian on it. And I think the Debian
specificity is a significant value add for the newbie anyway, though the
rest of us could just as well read a generic Unix book from several years
ago.)
Anyway, it would be fine to move the tutorial to the LDP server too, if
they want, for symbolic reasons. But again: someone has to do the work.
The one niggling misgiving I have is that IIRC the "official" LDP license
is non-free and in my view totally unacceptable for Debian; fortunately
none of the docs seem to actually use it. If the User's Guide had, for
example, I would have been forced to start from scratch rather than use
it.
> > and partly because document writers are
> > advanced Unix users who do not consider using X Window an issue. If
> > GNOME becomes standard GUI, we should add a tutorial on setting it
> > up and basic usage. As a first step, links to the existing GNOME
> > documentation could be added to Debian Tutorial (and/or User
> > Reference).
>
> It is so absurd and upsetting to me to hear talk about this group,
> which is already so overworked and understaffed, to try to go about
> and document this stuff.
>
Gnome will come with its own extensive documentation; Red Hat has hired a
full-time guy to write the docs.
However, let's not lose sight of this: documentation does need to cover
all the details, and it does need a certain amount of integration. It
probably makes sense to have Debian diffs for the Gnome docs, adding some
Debian-specific "gotchas," docs for Debian-specific enhancements, or
correcting anything in the docs that don't apply to Gnome as packaged.
These should be handled just as Debian source patches are handled.
Imagine the following: a user gets context-sensitive Gnome help on topic
foo, but Debian has changed foo, or the help for foo has some hand-wavy
line about "depending on your distribution..." This is bad, I think quite
obviously. Even if there's a README.Debian somewhere to dig through, Gnome
is supposed to be convenient and get us past things like finding obscure
READMEs.
I'm not saying we have time to deal with this, but we should recognize it
as a problem and realize that solutions to it would be a good thing, if we
had the time.
Adam, I would appreciate you forwarding this message or conveying the gist
of my comments to any of the people who have expressed displeasure with
the Tutorial's existence, and I would encourage them to contact this list
or me personally to talk about ways to get the advantages I've mentioned
of distribution-specificity while also working together on the generic
parts.
Havoc
Reply to: