Lessons learned - DocBook conventions for documentation practices

["G. Ken Holman" <gkholman@CraneSoftwrights.com>]

Hello again,

Regarding documentation practices for subcommittees, I was able to 
successfully deploy DocBook for our committee work with a twist that I 
think might be helpful to others.

In my draft stylesheet documentation I utilized a custom XML document model 
in order to get formatting features I wanted in the finalized formatting 
specifications.  I got exactly the result I needed, but the authored 
content was in a non-standard vocabulary.

Upon founding the subcommittee, I learned (I guess I shouldn't have been 
surprised) that the OASIS subcommittee standard for documentation is 
DocBook.  Yet DocBook doesn't provide some of the formatting features I 
wanted in our committee documents.

BTW, DocBook is fine for committee administrative documents and I've been 
successfully using the <article> model for agendas and minutes:

   <article>
     <title>FPSC Agenda 20030522 - 17:00UTC (13:00EDT/10:00PDT) - DRAFT</title>
     <articleinfo>
       <copyright><year>2003</year><holder>OASIS</holder></copyright>
       <pubdate>$Date: 2003/05/21 11:56:03 $(UTC)</pubdate>
     </articleinfo>

     <section>
     <title>
     Roll call and quorum</title>

     <para>
     ...

To get the numbering in the sections and table of contents, I invoke the 
XSLT processor with the section.autolabel=1 parameter.  Examples of our 
agendas and minutes are at:

  http://www.oasis-open.org/committees/download.php/2173/agenda-20030522.html
  http://www.oasis-open.org/committees/download.php/2245/minutes-20030522.html
  http://www.oasis-open.org/committees/download.php/2269/agenda-20030529.html

For the extra features I want and had in my custom model, I've created and 
tested a compromise that we will be trying out in our official committee 
formatting specification documents:  augmenting DocBook to produce DocBook 
where extra features are needed.  Through the use of the role= attribute in 
DocBook I can mark an otherwise standard DocBook construct as having extra 
meaning for our committee, and a "massaging" stylesheet takes the authored 
role= DocBook and augments it as desired to produce an augmented DocBook 
instance for publishing.  This augmented publishing instance can then 
formatted using standard DocBook stylesheets for any target output.

These custom requirements are only in two areas:  the formatting of tables 
of XPath addresses (where I add table heading rows and I massage the 
content to include zero-width spaces to promote cleaner line-breaking), and 
the collection and reporting of outstanding editorial notes that must be 
addressed before the document is completed.

At all times the instances validate against the DocBook document model, and 
standard DocBook stylesheets could be used with acceptable ... but for our 
formatting specifications we will run our authored instances through the 
massaging stylesheet to produce the publishing instances that can then use 
the standard publishing stylesheets.  This gives us the extra features in 
all published outputs.

This methodology focuses the committees custom work in a single place, 
independent of all publishing stylesheets, thus preventing having to 
customize all the target stylesheets duplicating the required functionality 
for each of the target presentation vocabularies.  Although I don't get 
precisely the desired appearance I could get by tweaking the formatting 
stylesheet, I can live with what I see knowing that I don't have to tweak 
all possible formatting stylesheets and just have the one "production" 
stylesheet to produce the "publishing" instance.

I've packaged this up for our committee members in the following ZIP file:

<http://www.oasis-open.org/committees/download.php/1810/fpscdoc-20030429-2000z.zip>http://www.oasis-open.org/committees/download.php/1810/fpscdoc-20030429-2000z.zip 


However, I must confess that getting committee members to try out the XML 
authoring and document production has been less than successful.  Perhaps 
editing a document in Word is easier, but I'm trying to convince (coerce?) 
members that we should practice what we preach about markup and try to use 
the document models for all our committee documents.  As of the last 
meeting not a single committee member had yet tried the new DocBook-based 
authoring environment.

I hope this helps.

................ Ken

--
Upcoming hands-on courses: (registration still open!)
-      (XSLT/XPath and/or XSL-FO) North America: June 16-20, 2003

G. Ken Holman                mailto:gkholman@CraneSoftwrights.com
Crane Softwrights Ltd.         http://www.CraneSoftwrights.com/o/
Box 266, Kars, Ontario CANADA K0A-2E0   +1(613)489-0999 (F:-0995)
ISBN 0-13-065196-6                      Definitive XSLT and XPath
ISBN 0-13-140374-5                              Definitive XSL-FO
ISBN 1-894049-08-X  Practical Transformation Using XSLT and XPath
ISBN 1-894049-11-X              Practical Formatting Using XSL-FO
Member of the XML Guild of Practitioners:    http://XMLGuild.info
Male Breast Cancer Awareness http://www.CraneSoftwrights.com/o/bc