Re: author's guide

[Gary Lawrence Murphy <garym@canada.com>]

Some thoughts:

I realize you've only just started, but so far, I don't really get any
sense of the OSWG book being any different in scope from Norm's book,
and I'd be reluctant to call his a "Practical Guide" --- with all due
respect, I mean I really like Norm, he's been super with putting up
with my endless stupid questions and his book is indispensible to me,
but in practical terms, the book is a reference to a language, not a
guide to solving real-world problems.

Such a book needs to focus on cookbook examples, of using DocBook to
solve a wide array of real-world problems. The structure of the book
should be driven by those real-world examples rather than on the
components and structure of DocBook itself.  This is not a criticism,
but if I was doing such a book, this is the approach I would take.

The OSWG DocBook outline starts with this approach.  There are
sections on 3 generic document types, but I wonder if there may be
different scenarios for each type of document. For example, is an
article an article, or are some of them a conference paper? How do I
manage a submitted chapter on a large book, a news article, a web-news
article ... 

Also, I'd begin with a simple reference page, then move up to an
article and end off with a whole book rather than the other way
around.  You can also have several books in a series, several series
in a line &c.  This is what I mean when I ask the LDP to create the
process first, and then to build a guidebook for feeding it.

Back to DocBook: The great advantages of DocBook is first to partition
content from presentation, but also to give DBMS-qualities to the
content structure. Because writers may not be accustomed to thinking
about their work in the wider context, it may make sense to talk about
these concepts in detail, and it may be these concepts that make it
difficult for all the open source agencies to work on this paper
together --- because each has different operational needs, each may
have different style guides.

The section on processing tools may be a winding garden path.
Rendering documents is easily a completely new book (or so it seems to
me right now ... I talk to DSSSL vs XSL people and they might as well
be speaking Greek) --- for the purposes of this doc, you may want to
follow Norm's lead and only tell them how to process the most basic
presentations, then start a parallel book on the various flavours of
stylesheet engines (or whatever they are called).  If content and
presentation are truly seperated, these are different audiences
anyway.

Personally, I have enough trouble trying to get HTML 'designers' to
leave content out of their equations and only deal with CSS coding ;)
They just can't let go of content, and writers can't let go of
presentation ... old habits die hard.

Authoring tools may be a really short section if you are only talking
about free editors ... basically, there is only one practical
solution: Emacs/psgml.  If you include the expensive commercial tools,
this section will go beyond the scope of your book as these are
generally full-featured XML or SGML editors and not limited to
DocBook.

FYI, I have a few references at http://www.teledyn.com/help/XML --- as
this quest leads me down a garden path, the bits I pick up along the
way get collected into this page.  It's no great shakes right at the
moment, but it is a start.

-- 
Gary Lawrence Murphy <garym@linux.ca>: office voice/fax: 01 519 4222723
TCI - Business Innovations through Open Source : http://www.teledyn.com
Canadian Co-ordinators for Bynari International : http://ca.bynari.net/
Moderator, Linux Education Group: http://www.egroups.com/group/linux-ed


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