DOC Added JSON and JSONSchema introduction, resources and XML intro

docs/source/index.rst

@@ -1,9 +1,11 @@
 .. image:: https://codecov.io/gh/octue/twined/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/octue/twined
   :alt: Code coverage
+  :align: right
 .. image:: https://readthedocs.org/projects/twined/badge/?version=latest
   :target: https://twined.readthedocs.io/en/latest/?badge=latest
   :alt: Documentation Status
+  :align: right
 
 ======
 twined
@@ -12,16 +14,33 @@ twined
 **twined** is a library to help digital twins talk to one another.
 
 
+.. epigraph::
+   "Twined" [t-why-nd] - encircled, twisted together, interwoven
+
+
 .. ATTENTION::
     This library is in very early stages. Like the idea of it? Please
     `star us on GitHub <https://github.com/octue/twined>`_ and contribute via the
     `issues board <https://github.com/octue/twined/issues>`_ and
     `roadmap <https://github.com/octue/twined/projects/1>`_.
 
 
+.. _digital_twins:
+Digital Twins
+=============
+
 A digital twin is a virtual representation of a real life being - a physical asset like a wind turbine or car - or even
 a human.
 
+.. figure:: images/digital_twin_hierarchy.png
+    :width: 500px
+    :align: center
+    :figclass: align-center
+    :alt: Hierarchy of digital twins
+
+    A hierarchy of digital twins. Each blue circle represents a twin, coupled to its neighbours. Yellow nodes are where
+    schema are used to connect twins.
+
 There are three reasons why you might want to create a digital twin:
     - Monitoring
     - Prediction
@@ -34,14 +53,6 @@ Coupling digital twins is generally even more useful. You might wish to couple y
 of the local power grid, and a representation of a factory building to determine power demand... enabling you to
 optimise your factory plant for lowest energy cost whilst intelligently selling surplus power to the grid.
 
-.. figure:: images/placeholder.png
-    :width: 500px
-    :align: center
-    :figclass: align-center
-    :alt: Just a figure placeholder for the time being
-
-    A hierarchy of digital twins. Each circle represents a twin, coupled to its neighbours.
-
 
 .. _aims:
 Aims
@@ -50,7 +61,14 @@ Aims
 **twined** provides a toolkit to help create and validate "schema" - descriptions of a digital twin, what data it
 requires, what it does and how it works.
 
-You'll find an in depth description in the :ref:`schema` section.
+The goals of **twined** are as follows:
+    - Provide a clear framework for what a digital twin schema can and/or must contain
+    - Provide functions to validate incoming data against a known schema
+    - Provide tools to create schema describing what you require
+    - Provide a function to check that a schema itself is valid
+
+Using schema, we can describe how digital twins connect and interact... building them together in hierarchies and
+networks. You'll find an in depth description in the :ref:`schema` section.
 
 
 .. _reason_for_being:

docs/source/schema.rst

@@ -4,7 +4,11 @@
 Schema
 ======
 
-This is the core of **twined**.
+This is the core of **twined**, whose whole purpose is to provide and use schemas for digital twins..
+
+.. _requirements:
+Requirements of digital twin schema
+===================================
 
 A *schema* defines a digital twin, and has multiple roles. It:
 
@@ -19,35 +23,23 @@ If this weren't enough, the schema:
 #. Must be human-readable
 #. Must be searchable/indexable
 
+Fortunately for digital twin developers, many of these requirements have already been seen for data interchange formats
+developed for the web. **twined** uses `JSON` and `JSONSchema` to interchange data between digital twins. If you're not
+already familiar with JSONSchema (or wish to know why **twined** uses `JSON` over the seemingly more appropriate `XML`
+standard), see :ref:`introducing_json_schema`.
 
-.. _schema_json:
-Using JSON Schema
-=================
-
-Fortunately for digital twin developers, many of these
-
-.. tabs::
-
-   .. code-tab:: py
 
-        import numpy as np
-        import es
+.. _specifying_a_framework:
+Specifying a framework
+======================
 
-        def main():
-            pass
-
-
-.. _why_not_xml:
-Why not XML
------------
-
-In a truly `excellent three-part blog<https://www.toptal.com/web/json-vs-xml-part-3>`_
+We cannot simply expect many developers to create digital twins with a `JSONSchema` then to be able to connect them all
+together. **twined** makes things slightly more specific
 
 
 .. toctree::
    :maxdepth: 0
    :hidden:
 
-   turbulence_coherent_structures
-   turbulence_wind
-   turbulence_tidal
+   schema_introducing_json
+