Documentation

Documentation is a vital part of any standard. In general, policy related open data standards need both:

• Technical reference documentation

and

• Supporting documentation

These need to be approached differently, as the patterns below outline.

Technical approach

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.

Documentation patterns

Documentation patterns

• Single Source of Truth
• Issue tracker
• Version control and changelogs for the schema and documentation
• Governance process for normative changes to the schema and documentation
• Branch and release management
• Automated build processes
• Reproducible builds
• Deployment and rollback