Documentation is a vital part of any standard. In general, policy related open data standards need both:
- Technical reference documentation
- Supporting documentation
These need to be approached differently, as the patterns below outline.
The documentation websites we maintain are static HTML sites generated using sphinx.
Sphinx has the ability to process and integrate documentation from different sources using directives. With Sphinx you can do things like gathering field descriptions from a schema file and compiling them as a table in a document, allowing you to use a component of a standard to document the standard itself.
We have created a number of custom directives documented here.
reStructuredText is the native input format for Sphinx builds. However, with the bridge library recommommark, it is possible to use input files in markdown.
We maintain a custom sphinx-base project to use when starting new documentation sites.