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

Re: Outline for Author's Guide

Agreed the relative dearth of features in the old linuxdoc will not
make for a complete DocBook, but we don't want to overwhelm anyone.
Adding a bunch of sample widgets because we think they may be needed
may just confuse people.

We can start with the stripped down linuxdoc conversions, then perhaps
add some widgets to them --- if people like them, we have just upgraded
an old doc, and if people don't like them, we don't have two dozen authors
all working in parallel putting these widgets into every new document.

I'll stick to my guns: Even Norm Walsh's DocBook guide shows that even
he has very little experience in how such documents are actually used:
The review people at MCP have already been responsible for many
changes and additions to his online book, all done in the name of
wide-audience useability.  If Norm can't get it right flying blind, do
we really have a chance?  I'm only suggesting we walk before we run, and
maybe even crawl first.

What I would like to see compiled, though, rather than an Author
Guide, is a cookbook of DocBook tags.  We can elaborate on where and
why we want to use each later as we see where things fit in the real
world, but to begin with, we can collect bits into a reference for how
the tags are used, for example, the discussions recently on URL->ULINK
and what values we want for revision tags, where to put the CVS tags
and all that.

By working with the linuxdocs, we can see what exactly is missing, do
some experiments to add them in (by hand if necessary) and from the user
feedback, we can formulate policies; once we have enough policies to 
make for a complete document, we can then announce that all future docs
will be LDP-DocBook DTD and distribute the DTD, our stylesheets and our
Author Guide.

Gary Lawrence Murphy <garym@canada.com>  TeleDynamics Communications Inc
Business Telecom Services : Internet Consulting : http://www.teledyn.com
Linux/GNU Education Group: http://www.egroups.com/group/linux-education/
"Computers are useless.  They can only give you answers."(Pablo Picasso)

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