improve documentation

put in the start of

* concepts
* use cases

build.gradle.kts

@@ -1,7 +1,7 @@
 import org.gradle.kotlin.dsl.accessors.runtime.addDependencyTo
 
 plugins {
-        id("net.ivoa.vo-dml.vodmltools") version "0.5.3"
+        id("net.ivoa.vo-dml.vodmltools") version "0.5.4"
         `maven-publish`
         id("io.github.gradle-nexus.publish-plugin") version "1.1.0"
         signing
@@ -27,7 +27,6 @@ vodml {
         outputDocDir.set(layout.projectDirectory.dir("std/generated"))
         outputSiteDir.set(layout.projectDirectory.dir("docs/generated"))
 
-        modelsToDocument.set("proposal,proposalManagement")
 }
 
 /* uncomment this if not using the eclipse vodsl plugin to edit the vodsl
@@ -85,7 +84,7 @@ tasks.register<Copy>("copyJavaDocForSite") {
 
 tasks.register<Exec>("makeSiteNav")
 {
-        commandLine("yq","eval",  "(.nav.[]|select(has(\"AutoGenerated Documentation\"))|.[\"AutoGenerated Documentation\"]) += load(\"docs/generated/allnav.yml\")", "mkdocs_template.yml")
+        commandLine("yq","eval",  "(.nav | .. |select(has(\"AutoGenerated Documentation\"))|.[\"AutoGenerated Documentation\"]) += load(\"docs/generated/allnav.yml\")", "mkdocs_template.yml")
         standardOutput= file("mkdocs.yml").outputStream()
         dependsOn("vodmlSite")
         dependsOn("copyJavaDocForSite")

docs/concepts.md

@@ -0,0 +1,15 @@
+Main Concepts
+=============
+
+A [Principal Investigator](../generated/proposal/Person/) is interested in one or more [Targets](../generated/proposal/Target/) and they decide that they want to create an [Observing Proposal](../generated/proposal/ObservingProposal/) to study them. They write a [Science Justification](../generated/proposal/Justification/) to try to persuade the [Time Allocation Committee](../generated/proposalManagement/TAC/) for a particular [Observatory](../generated/proposal/Observatory/) to allocate some [Observations](../generated/proposal/Observation/) on one or more [Telescopes](../generated/proposal/Telescope/) that they operate.
+
+
+
+
+
+## Detailed Documentation
+
+Autogenerated documentation for the models
+
+* [ProposalDM](generated/proposaldm.vo-dml.md)
+* [ProposalManagementDM](generated/proposalManagement.vo-dml.md)

docs/index.md

@@ -27,13 +27,7 @@ The proposal management part of the model adds extra information that the observ
 and to provide a method of scoring the proposal. This is deliberately created as a separate part of the overall model to help
 to enforce the separation in functions so that the same proposal might be more easily submitted to several observatories.
 
-## Detailed Documentation
-
-Autogenerated documentation for the models
-
-* [ProposalDM](generated/proposaldm.vo-dml.md)
-* [ProposalManagementDM](generated/proposalManagement.vo-dml.md)
-
+The main concepts within the data models are [described in more detail](concepts.md)
 
 ## Acknowledgement
 

docs/usecases/intro.md

@@ -0,0 +1,14 @@
+Motivating Use Cases
+====================
+
+The use cases that have driven the design have been divided into two main categories
+
+* [Example Telescopes](telescopeDescriptions.md)
+* [Example Observing types](observationDescriptions.md)
+
+In both these cases the Data Model is exercised by creating instances using the Java code generated from the models and running some basic unit tests on serialization. The code is based at [this location](https://github.com/ivoa/ProposalDM/tree/master/src/test/java/org/ivoa/dm/proposal/prop). Writing these tests allows exploration of various aspects of the quality of the design su
+ch as;
+
+* verbosity/expressiveness
+* ease of manipulation of parts of the model
+* contradictions in meaning between different parts of the model.

docs/usecases/telescopeDescriptions.md

@@ -0,0 +1,20 @@
+Telescope Description Use Cases
+===============================
+
+* e-MERLIN
+
+[e-MERLIN](https://www.e-merlin.ac.uk) is a radio interferometer operated by the University of Manchester
+
+** Instrument description
+
+TBC
+
+** TAC operation
+
+TBC
+
+** Example code
+
+The emerlin example is [here](https://github.com/ivoa/ProposalDM/blob/master/src/test/java/org/ivoa/dm/proposal/prop/EmerlinExample.java)
+
+

mkdocs_template.yml

@@ -15,5 +15,11 @@ markdown_extensions:
           format: !!python/name:pymdownx.superfences.fence_code_format
 nav:
   - Introduction: index.md
+  - Model Design:
+     - Concepts : concepts.md
+     - Use Cases:
+        - Introduction: usecases/intro.md
+        - Telescopes: usecases/telescopeDescriptions.md
+        - Observations: usecases/observationDescriptions.md
   - AutoGenerated Documentation:
-  - JavaDoc: generated/javadoc
+  - JavaDoc: generated/javadoc/index.html