Sample of Assembly

["Rowland, Larry" <larry.rowland@hp.com>]

I have coded up a sample of an assembly, which is attached.

As a caveat, my background is in software documentation.  I have found
the models in modular documentation presentations much more appropriate
for hardware documentation than software documentation.  You might
want someone to take a crack at this who is a big proponent of modular
documents.  While I do a good deal of content reuse, it is not generally
based on CMS concepts or modular development.

The attached file is presumed to be documenting a document build 
environment that uses Ant to provide build targets from the command line
and also has a Web based GUI with a Subversion repository to provide
authoritative builds based on pulling top of tree of source files and
executing the same Ant targets used to build from the command line.

The files referenced by both resource collections defined below are
assumed to be well formed DocBook block elements, but not much more
than that.  I started out assuming that they were all articles, but it
turned out that assumption was not necessary for the scenario by the 
time the coding was done.

I did not attempt to exercise all the features of the assembly, just
to create something reusing content across multiple documents.

The file includes:

 - two resource collections, one local and one a remote server, assumed
   to be a Subversion repository

 - A help system, defined using a toc element

 - A user guide, defined using a toc element

 - A tutorial, designed using a relationship (this assumes a tutorial
   player is available to the help system)

I did not attempt to define anything using calls to a content
management system, since I don't know the calling syntax for any of
them, and I am familiar with accessing Subversion repositories.

I am not entirely sure the use of the relationship is appropriate.  The
examples in the proposal looked like collections of metadata that would
be included with the content rather than something you would author
externally.

I had to hack some schemas to complete the markup.  While I fully 
anticipated modifying the assembly schema, since it was what we are
working on now, I also had to modify the schemas in toc.rnc.  That may 
well indicate that we need something other than toc (maybe a generic 
hierarchy element of some sort) rather than reusing the toc element.
It may also indicate I just don't understand how to construct a toc
using DocBook, since it has always been done for me automatically.

I would also suggest that the resources elements either be first in the
schema or that all elements be freely intermixable inside an assembly,
since that may help with some of the cognitive model that the author
has to develop.

Regards,
Larry


=======================================================================
[ Larry Rowland             | If you want to build a ship, don't drum ]  
[ ESS/ATG                   | up the men to gather the wood, divide   ]
[ Hewlett-Packard           | the work, and give orders. Instead,     ]
[ 3404 East Harmony Road    | teach them to yearn for the vast and    ]
[ Fort Collins, CO  80528   | endless sea. - Antoine de Saint Exupery ]
[ Phone: 970/898-2280       +-----------------------------------------]
[ E-Mail:larry.rowland@.hp.com                                        ]
=======================================================================

assembly-sample.zip