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

Re: Notes for DDP writers

a quick thought.

The LDP is the Linux Documentation Project.   A very non-specific 
approach to documenting things related to Linux.

The DDP is the Debian Documentaiton Project.  A very specific approach
to documenting things related to Debian GNU/Linux.

ok...we all agree on this.  (or at least 99%)  

One thing I know that would drive me nuts is if I had to look
at several different manuals to find the information dealing with Debian.

People looking for help with their RedHat install are going to go to
RedHat first..the LDP (or some other place).  They are not going
to go to Debian...and vice versa.  

For someone using Debian...they are going to look on their system
first...Debian's home page next...(which will lead them to this
documentation if it's not on their system already) and then off
to the LDP or elsewhere.

I personally think we should write documentation about Debian specific.  Going
into as much detail as necessary to explain it.  If the user needs more in
depth information about whatever, then we should pawn them off to the LDP.

Now..if we feel that the LDP doesn't have enough info on said item, then
we should help them out... (when it's a general Linux item)...but I do
believe we shouldn't stop exactly when we start to cross over into the LDP
area.  We can't make a user stop mid stream and go somewhere else to finish.
We should give them a start to end on the basics...then ship them off for
the advanced to the LDP.  (Unless the advanced is a Debian specific thing)

Just my two bits.


On Sun, Feb 14, 1999 at 02:50:23AM -0600, Havoc Pennington wrote:
> 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
> 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
> --  
> To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
> with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
---end quoted text---

Ivan E. Moore II                                      Rev. Krusty
http://www.tdyc.com				 rkrusty@tdyc.com
 Imagination is more important than knowledge  - Albert Einstien
GPG KeyID=0E1A75E3
GPG Fingerprint=3291 F65F 01C9 A4EC DD46 C6AB FBBC D7FF 0E1A 75E3

Reply to: