Logic Works 5 - Documentation -- The format of the Guide

The format of the Guide

1. Introduction

Somewhere along the line the Gentoo Linux documentation was recommended as an exemplar for this documentation project, and the format just kind of stuck. Gentoo’s documentation was attractive for a couple of reasons.

One, it was concise and easy for the lay person to follow, which is of course an artifact of good writing, not a good file format. Trying to duplicate the voice and tone of if would be a step in the right direction.

Two, the fact that it separates content and presentation with XML and XSLT makes it extremely portable. For those unfamiliar with XSLT (eXtensible Stylesheet Language Transformation), its relation to XML is sort of similar to CSS's relation to HTML, except where CSS only modifies the load-time display of the HTML, an XSLT actually converts an XML file to some other textual format, in our case HTML.

Why XML

What XML/XSLT allows us to do is disentangle the content meat of our guide from its display-like skeleton without, and this is important, the need for dynamic load time page generation like you would get from PHP/MySQL. PHP/MySQL would be great if we knew that these technologies would be available to us on delivery. They may, but they may not. We may need to be packaging our documentation for user download or inclusion with an assignment file, in which case static HTML is our only option. With XML/XSLT all of this static HTML can be regenerated from a single script. As a bonus, we can swap out XSLT’s to create different display versions of our documentation like, say, a pretty screen version and a bare-bones ready for printing version, without having to touch the original content.

2. The GuideXML format

It’s Simple

We’re using a stripped down version of Gentoo’s Guide XML Document type that is excessively easy to learn. If you know HTML, or have had any experience with XML, you can probably get the gist of it just by looking at it. So here’s the Guide XML for this page:

guideformat.xml

You can see that each page is contained within a <guide> tag, and that there are some little meta-data tags (<date>,<abstract>,<version>) before the guide starts dividing itself into <chapter>'s (automatically numbered) which are then divided into smaller <section>'s. Each section contains a <body> and a set of <p>aragraphs

Those names can be a little misleading. We’re not talking chapters of the length you’d typically find in a book, just whatever divisions makes sense. See the Gentoo Documentation for a good general idea.

3. Other Useful Tags

Additionally there are some custom tags that are helpful in drawing attention to certain kinds of information.

Note

Wrapping anecdotal text in <note> tags gets you:

Note: This is a note. Heed its apropos advice.

Important

Wrapping text crucial to the discussion in <important> tags gets you:

Important: This is a important. Pay attention.

Warning

Finally, wrapping text that could derail the user actions or understanding in <warning> tags gets you:

Warning: Weighty consequences hinge on this information.

4. Wrap up

I hope you’ve found this documentation useful. If you have any questions, comments or errors regarding the format, contact Peter (gtg609b). As for any future changes, while the XLST’s are like to change as feedback is received on the site design, the Guide XML format should not. Happy documenting.