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.