Add more text about documentation

Author: Bjwebb

docs/development/documentation.md

@@ -5,13 +5,36 @@
 
     sections to add:
 
-    * sphinx for documentation
     * example data :ref:`component-example-data`
-    * designing good documentation
-       * visual design
 
 ```
 
+## Designing good documentation
+
+* Designing an appropriate structure to the documentation
+* Writing specific bits of copy
+* Visual design
+
+```eval_rst
+.. todo::
+    Write more about why visual design is important
+
+```
+
+```eval_rst
+.. _section-documentation-technical:
+```
+## Technical approach
+
+The documentation websites we maintain are static HTML sites generated using [sphinx](http://www.sphinx-doc.org/en/stable/index.html).
+
+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](https://github.com/OpenDataServices/sphinxcontrib-opendataservices).
+
+[reStructuredText](http://docutils.sourceforge.net/rst.html) 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](https://github.com/OpenDataServices/sphinx-base) project to use when starting new documentation sites.
 
 ## Documentation patterns
 

docs/development/stages.md

@@ -83,7 +83,7 @@ The released version of a standard is production ready, and no further changes w
 
 ## Revision
 
-A standard will periodically be revised. See the section on versioning for more information. 
+A standard will periodically be revised. See [Governance and Revision](governance) for more information. 
 
 ```eval_rst
 .. todo::

docs/development/tooling.md

@@ -1,12 +1,8 @@
 # Tooling
 
+For the tooling we use to build thedocs itself, see [Documentation -> Technical approach](section-documentation-technical)
 This section details the tooling we use as part of our standard development.
 
-For documentation we make extensive use of [sphinx](http://www.sphinx-doc.org/en/stable/rest.html)
-
-We maintain a custom [sphinx-base](https://github.com/OpenDataServices/sphinx-base) project to use when starting new documentation sites.
-
-We have created a number of [custom directives documented here](https://github.com/OpenDataServices/sphinxcontrib-opendataservices).
 
 ## Tooling components
 

docs/patterns/documentation.md

@@ -242,7 +242,7 @@ Releases are named: `Major__minor__path` e.g. `1__0__3`, `1__1__2`
 ### Problem
 
 Normally, building the standard documentation and publishing the schema is a complicated process involving many steps to run and test.
-To save time, these need to be run automatically. Feedback needs to be given to the documentation or schema writers to check if their changes look correct. 
+To save time, and to avoid mistakes, these need to be run automatically. Feedback needs to be given to the documentation or schema writers to check if their changes look correct. 
 Also, checks regarding the integrity of the documentation and schema need to be run for every change made.
 
 ### Solution
@@ -252,7 +252,11 @@ This means that the integrity tests are run and you can see version of that bran
 
 ### Method
 
-We use Travis on github, both to run the tests and to push a built version of the docs/schema to a development server. We store private server access details on github outside our public build scripts.
+We use two different automated build services, for different projects:
+
+(1) [Read the docs](https://readthedocs.org/) is designed specifically for building Sphinx docs. It will rebuild a version of the documentation every time a commit if pushed to the corresponding branch on GitHub. Read the Docs being designed specifically for Sphinx is useful because it will automatically hosts the docs, and provides a version/language switcher out of the docs. It gives a lot of control (e.g. you can have whatever custom directives and theming you want, you can point a custom domain at it), but is less flexible than a generic build service. It also requires a manual step to add a new branch/version to the docs. We use Read the Docs for lots of smaller docs sites
+
+(2) [Travis](https://travis-ci.org/) - is a generic build service (again building every time something is pushed to GitHub), so requires a bit more setup than Read the Docs, but also gives you maximum flexibility over what commands get run. It can also run tests of the documentation/schema before the build. It doesn’t host docs, but can be set up to push the built docs to a hosting provider of your choice.
 
 ### Example