Some doc updates

Author: pgleeson

README.md

@@ -1,10 +1,8 @@
 # Modelspec
 
-
 [![Continuous builds](https://github.com/ModECI/modelspec/actions/workflows/ci.yml/badge.svg)](https://github.com/ModECI/modelspec/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/modelspec)](https://pypi.org/project/modelspec/)
 
-
-Functionality for specifying the structure of models & enabling automatic serialization to them (e.g. in JSON and YAML format).
+Functionality for specifying the allowed structure of models, facilitating the creation of APIs in Python for handling the models & enabling automatic serialization of instances of them (e.g. in JSON and YAML format).
 
 This package is being used by [NeuroMLlite](https://github.com/NeuroML/NeuroMLlite) & [MDF](https://github.com/ModECI/MDF).
 

docs/sphinx/source/api/Introduction.md

@@ -1,10 +1,8 @@
 # Modelspec
 
-
 [![Continuous builds](https://github.com/ModECI/modelspec/actions/workflows/ci.yml/badge.svg)](https://github.com/ModECI/modelspec/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/modelspec)](https://pypi.org/project/modelspec/)
 
-
-Functionality for specifying the structure of models & enabling automatic serialization to them (e.g. in JSON and YAML format).
+Functionality for specifying the allowed structure of models, facilitating the creation of APIs in Python for handling the models & enabling automatic serialization of instances of them (e.g. in JSON and YAML format).
 
 This package is being used by [NeuroMLlite](https://github.com/NeuroML/NeuroMLlite) & [MDF](https://github.com/ModECI/MDF).
 

docs/sphinx/source/api/Quickstart.md

@@ -15,18 +15,19 @@ More details, and importantly, how to set up a [virtual environment](https://vir
 
 ### Simple example
 
-A basic example which illustrates how to create the specification for a document(model) and create serialized instances can be found [here](examples/README).
+A basic example which illustrates how to create the specification for a document (i.e. the model definition for a document) and create serialized instances can be found [here](examples/README).
 
 ### Serialization formats
 
-Python scripts can be used to generate the specification of a type of model(e.g. [this](https://github.com/ModECI/modelspec/blob/main/examples/document.py)), but the models are saved in standardized format in either text based [JSON](https://github.com/ModECI/modelspec/blob/main/examples/document.json) or [YAML](https://github.com/ModECI/modelspec/blob/main/examples/document.yaml) formats or in binary [BSON](https://github.com/ModECI/modelspec/blob/main/examples/document.bson) format. Support for XML serialization is under development.
+Python scripts can be used to generate the specification of a type of model (e.g. [this](https://github.com/ModECI/modelspec/blob/main/examples/document.py)), but the models are saved in standardized format in either text based ([JSON](https://github.com/ModECI/modelspec/blob/main/examples/document.json) or [YAML](https://github.com/ModECI/modelspec/blob/main/examples/document.yaml)) formats or in binary ([BSON](https://github.com/ModECI/modelspec/blob/main/examples/document.bson)) format. Support for [XML](https://github.com/ModECI/modelspec/blob/main/examples/document.xml) serialization has recently been added.
 
 ### Current formats using modelspec
 
-#### MDF
+#### MDF (Model Description Format)
 
-MDF uses modelspec to create the structure of its models and convert the models into serialized formats such as JSON, YAML, and BSON.
+[ModECI's MDF](https://modeci.org/quickstart) uses modelspec to create the structure of its models and convert the models into serialized formats such as JSON, YAML, and BSON.
 
 #### NeuroML
 
-NeuroMLlite uses modelspec to create the structure of its models and convert the models into serialize formats such as JSON, YAML, and BSON.
+[NeuroMLlite](https://github.com/NeuroML/NeuroMLlite) uses modelspec to create the structure of its models and convert the models into serialize formats such as JSON, YAML, and BSON.
+The XML serialisation of modelspec will be useful for integrating NeuroML 2 files into the framework, see [here](https://github.com/ModECI/modelspec/tree/main/examples/neuroml2).