Re: [RFP] A more maneagable way to include documentation
On Mon, Mar 20, 2000 at 02:57:06PM -0500, James A. Treacy wrote:
> > That I think has been the whole problem: how to move only the finished
> > stuff to /doc/ddp/, without the development stuff. I think we should edit
> > the DDP web pages once we move them to the website so that all references
> > to unfinished stuff are removed.
> >
> > Perhaps the stuff in development should be put on (and linked to) another
> > machine so that it doesn't get mirrored? We have several machines to pick
> > from.
>
> Actually, since the docs aren't that big, it wouldn't matter if they
> get mirrored. What is more important is that we only link the stable
> documents.
That's the point. There are links to both `stable' and `unstable' versions
of each document (presuming both exist, of course) on the DDP pages.
Besides, is the mirroring done by pulling a whole directory structure
(rsync), or just by following the (in-site) links from to toplevel
index.html (wget)? I never bothered to ask this...
> The authors of the documents also need to create tags for important
> sections of their document so links can be made to those sections in a
> robust way. Additionally, The tags need to be documented.
Hm... how do you make a tag (<A NAME="bla">, right?) in DebianDoc SGML?
Does <label> work? I have to go read the specs... <blush>
> Two other items. First, the contact address should be clearly marked at
> the beggining of all docs. We need to make it easy for people to submit
> feedback.
I wouldn't force it to be at the very beginning: as long as it is provided
and it works (i.e. it points to an address behind there is someone that is
really going to read and answer it), it should be fine.
I say this because the FAQ will have a <ref id="authors"> in the <author>
tag, so this wouldn't be the compliant to what you propose. I imagine some
other documents could do the same.
BTW what seems confusing to me is that people fill the <author> tags with
the names and addresses of all contributors to the document. Frankly, I
don't think the reader needs to know about all of those e-mails (especially
when there is another unique address to contact the maintainer), and the
more times you mention an e-mail, the more spammers mail you :(
> Second, all documents should include version numbers. This is
> especially important since they are being distributed in multiple
> places (web, archive /doc section (both ftp and on CDs), and as packages).
AOL.
--
enJoy -*/\*- don't even try to pronounce my first name
Reply to: