Documentation

A note on documentation: early on the decision was taken to use Markdown for all documentation within the team. While XML document standards like DocBook and OxygenDoc would seem to be the obvious choice, Markdown was chosen for the reason that almost no training is required to use it—in fact merely using plain text will be accepted as valid and suitably rendered. This would reduce the workload on the content delivery team who would not have to learn another documentation standard, the assumption being that any form of documentation is preferable to no documentation at all. It should also be noted that Ant documentation cannot use these other (XML) standards as no tags are permitted inside its <description> tag—using Markdown therefore allowed the team to use a uniform documentation system. However, as part of the library described below some XSLTs were created to extract the Markdown documentation from Ant build files, XSLTs and Schematrons which could then be used to produce HTML for deployment.