InterestGroupDocumentation

Group contact point: MatthewTyleeAtkinson

Index:

1. Accessible Multimedia Documentation with DocBook XML
   1. Educational Uses
2. Getting Started
   1. Getting to Know DocBook
   2. Build System with Accessibility-Optimised Stylesheets
3. Further Information & Request For Comments

Accessible Multimedia Documentation with DocBook XML

DocBook XML is a standard for writing technical documentation. It has a number of features/advantages over traditional documentation formats such as plain text and .doc:

• Simplicity: You specify the semantics - what each part of the document means - and the system formats the document according to what type of output you want.

• One Source, Multiple Outputs: All sorts of output, such as HTML, RTF, PDF, WinHelp, JavaHelp and Plain Text can be generated automatically from one source XML document.

• Consistency: The formatting is done according to rules developed by professional typesetters and features such as navigational links are generated automatically for you.

• Flexibility: The output can be tailored easily using technologies like XSL. I have used this to make more accessible multiple-page HTML output than the standard DocBook distribution provides.

• Cross-Platform: Both the tools and output can run on all modern contemporary OSes. You can rest assured that documentation won't be a stumbling block when you expand into other platforms.

And some benefits I've found relating specifically to game development:

• Multimedia content such as sounds can be linked to from the documentation. This allows users to learn sounds from within the manual and also link to web-based material seamlessly.

• The manuals can be packaged and deployed and updated easily.

• Using DocBook saves a lot of time during development.

Many companies and organisations are using DocBook nowadays and enjoying these benefits. For some examples of DocBook game manuals, please visit http://docs.agrip.org.uk/.

Educational Uses

DocBook is an ideal format for creating lecture notes and handouts. You can include MathML and material written with other XML-based standards (such as SVG) inside DocBook publications. The results can be made accessible, thus eliminating the problem of having to maintain a "normal" and "accessible" version of the material.

In addition, alternative text (D-links) can be added easily to images and there are a number of GUI XML editors available that are DocBook-aware. It really is a great tool for creating educational material. Coupled with the accessibility-optimised stylsheets in the build systems available below, it's a winner!

back to top

Getting Started

This section aims to provide the minimum information you need to get using DocBook in your projects. you can use a GUI DocBook Editor (one is linked to for Windows) but you may well find that with a text editor such as Vim and some extra XML tools, you'll be more productive.

Getting to Know DocBook

Here are some useful "primer" articles on DocBook:

• DocBook Crash Course

• DocBook Demystification HOWTO from the Linux Documentation Project

• DocBook Quick Reference

• The Official News and Reference Site

Build System with Accessibility-Optimised Stylesheets

There is a build system that you can use to create accessible HTML format documentation on Linux and Windows. The build system eases the process of using DocBook (specifically on Windows). All the tools you need have been collected together and a front-end has been written to help you generate the documentation from the XML files you write.

Please comment on the system via the mailing list. You can download it from http://tylee.f2s.com/agdev/agdbk.zip

back to top

Further Information & Request For Comments

Please contact me to let me know what else you would like to have included here, or if you have any questions about DocBook and using it.

back to top