← Back to team overview

ubuntu-manual team mailing list archive

Re: Documentation pool sample content


On 07/14/2010 12:27 AM, Jim Campbell wrote:
Hi All,

2) Put the content into the different formats. Format assignments are as follows: - Docbook v5 - Could a member of the docs team take care of this one? Perhaps Kyle? Mdke?
 Yes I can put some docbook 5 there.

This is perhaps a reasonable place to note that the content pool's element "vocabulary" (its set of structures for indicating sections, paragraphs, etc) must, I think, support *all* required fundamental structures of all delivery formats. By which I mean, suppose a delivery format is going to use numbered lists, then clearly the source format needs to support numbered lists. So, if a proposed content pool source format does not support structures that are required by target delivery formats, this would seem to rule this source format out.

So what are the required "structures" or element vocabularies that the source format must support? Well, as a start, here's some guesswork:

* overall container (in docbook, that's <article>, since it is perfectly topic oriented (despite the oft-repeated and, I believe, technically incorrect view that docbook is only suitable for books, manuals, and linear documents))
 * container title and other meta info (author, revision, etc.)
 * header 1
 * header 2
 * paragraph
 * code snippets
 * media (images, videos, sounds clips)
 * bulleted lists
 * numbered lists
* links (this is a topic where things can go wrong though. I'd argue topics should only link to other parts of themselves or they can too easily break. The user portal (whatever it is in each case), should provide facilities for finding topics of interest.)
 * tables
 * inline tagging (emphasis, other)

It is remarkable that almost everything can be written using just those constructs (I probably forgot some...?)

Naturally, there has to be mechanized means of converting all of these to their equivalents in the delivery formats, or else, I would argue, the source format does not meet requirements.

Given this "convertibility" requirement, there should be an "official" list of elements that are allowed to be used in the source format. To be an allowed element, it has to be shown to be convertible to every delivery format.

I think docbook is the most likely candidate for the source format because:
* It already has vocabulary (element structures) for all needs (indeed, one can argue its vocabulary is too big) * It already has rich conversion capabilities (although perhaps not yet to Mallard. This could be created though.)

One potential pitfall with docbook would be *not restricting the set of allowed elements*. Therefore the need for a managed list.



Follow ups