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

Re: Debian User's Manual

"Adam P. Harris" <apharris@burrito.onshore.com> writes:

> robert havoc pennington <rhpennin@midway.uchicago.edu> writes:
> > On 25 Jun 1998, Adam P. Harris wrote:
> >> This site has *everything* to do with the documentation project,
> >> Robert.  It just has not much to do with your particular effort in
> >> that respect.
> > It's the main developer's page. It has a link to the DDP page.  It
> > has links to developer docs. But I don't think it's the most
> > important issue here.
> No, Oliver raised it though.  I was responding to that.
> > Futzing means a documentation indexing system, a new DTD, umpty
> > zillion planned documents, and not much documentation writing. I
> > should qualify that: not much documentation writing intended for end
> > users, since I started paying attention last summer or so.
> Maybe I'm short-sighted or "futzing" by personally prioritizing a
> consistent document heirarchy (basically done) and a metadata standard 
> (close to done), although I personally think it's important.

I agree with Adam on this.  Once the documentation hierarchy is in
place both the end-user and the Debian developer will have easy access 
to a huge amount of documentation.  This absolutely does not mean we
should wait with writing other documentation, but a consistent overall 
"look and feel" definitely helps in finding what one is looking for. 

By the way, it's very healthy from time to time to take a step back
and look whether we're heading in the right direction.  The discussion 
about the DTD was one of such moments.  I've seen quite some similar
discussion on debian-devel resulting in some very "unique" features 
like e.g. the emacsen-common facility for emacs add-on package. 

> Not to mention that Igor and I have quietly and without much ado been
> editing and working on the Installing Debian 2.0/x86 documentation.  I
> lost a good deal of sleep earlier this week working on it, making it
> more consistent and readable, adding laptop installation instructions.
> Anyone hoping to contribute there should contact <igor@igoria.net> or
> just send patches off <URL:http://www.igoria.net/install/install.sgml>.
> > Anyway, let's not get into a silly argument. Clearly both a doc
> > coordinator and doc writing are needed. But please, no one wait for
> > those web pages to get updated before writing docs.
> No, but people are more likely to contribute if they see a larger
> vision.  And if they see that their work is getting incorporated into
> the document.  I hope you've been able to track down the contributions
> of others and patch those in, as Oliver and others mentioned.
> I guess the lesson, here, Robert, is that you're not going to win
> points with or other developers by disparaging their efforts.  We're
> all volunteers here.

I couldn't agree more. 

> By the bye, you haven't seen me contributing to the tutorial because I
> think it's much too ambitious.  I would rather see a guideline for
> experienced FSF/Linux users getting to know Debian, and how it might
> differ from what they expect.  I guess I see a general Unix intro,
> including permissions, the shell, X11, TeX (!), lpr, etc etc., as just
> too large of a project.  I'd rather see a guide (or is there one
> already?) explaining the Debian way:
>   * don't install stuff in /usr
>   * how and when to use dpkg, apt, dselect, dftp
>   * checking bugs on the BTS
>   * ...
> I wish you the best of luck, however.  Please don't get frustrated or
> angry that different people have different priorities and goals.  You
> have to have a thick skin and a bit of pigheadedness to be a debian
> developer.
> Oh, one last thing.  How does the Tutorial relate to the Debian User Manual
> (http://fatman.mathematik.tu-muenchen.de/~schwarz/debian-doc/manuals.html#users)?
> It seems that there's a *lot* of overlap?

The User's Manual has been split into the Tutorial and a Reference
Guide.  This has only not been reflected on the DDP home page yet. 

> .....A. P. Harris...apharris@onShore.com...<URL:http://www.onShore.com/>


Ardo van Rangelrooij
home email: ardo.van.rangelrooij@tip.nl, ardo@debian.org
home page:  http://www.tip.nl/users/ardo.van.rangelrooij
PGP fp:     3B 1F 21 72 00 5C 3A 73  7F 72 DF D9 90 78 47 F9

To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org

Reply to: