standardizing standards formats

Working towards a common organization and formatting of standards documents

Author: cmbarton

content/en/standards/documentation/_index.md

@@ -12,15 +12,20 @@ weight: 2
 These standards promote documentation needed for others to understand a model and reproduce its results.
 {{% /standards-preamble %}}
 
+## Overview of Documentation Standards
+
+## Goals for Documentation Standards
+
 Documentation of a model, together with the provided model code, needs to facilitate the understanding of the intentions of the developer, and make the model easier to test, use, and link to other models. It should also describe assumptions made about phenomena being modeled and what information is used to create and test the model.
 
 We suggest three main categories of documentation:
 - Metadata
 - Methods and theoretical foundation
 - Implementation
 
-### Metadata
+## Minimal Documentation Standards
 
+### Metadata
 - Name and version of the model
 - Model project page (organizational website or repository, if available)
 - Description of the model, including its purpose or goals and the type or formalism of the model  (e.g., system dynamic, agent based model, machine learning), preferably accompanied by relevant keywords
@@ -36,9 +41,7 @@ We suggest three main categories of documentation:
 - References to reports or publications where the model is used
 - Changes since the last version (if the model is an update) including bug fixes, new features, or other substantive modifications, where appropriate.
 
-
 ### Methods and theoretical foundation
-
 - Assumptions: What are the key assumptions made that define the dynamics of the model?
 - Model structure: provide a flow diagram of the model.
 - Equations: What are the equations of the model?
@@ -49,7 +52,6 @@ We suggest three main categories of documentation:
 ### Implementation 
 
 #### Input/Output and Variables 
-
 - Key input parameters and their values and domain ranges and units (minimum input requirements for model operation and default values, where appropriate) 
 - Initial conditions  
 - Forcing functions that affect the dynamics of the model.  
@@ -58,17 +60,19 @@ We suggest three main categories of documentation:
 - Provide sample runs that illustrate the dynamics of the model.
 
 #### Validating installation
-
 - Provide sample input and output files, including run script, such as a cookbook or benchmark
 
 #### Model evaluation, uncertainty, and sensitivity
-
 - Provide data used for calibration and evaluation of the model, if data are public. 
 - Describe how calibration and evaluation to verify the accuracy of the model were performed. 
 - List of publications on evaluation, uncertainty, sensitivity analyses for your model
 - Describe or provide benchmarks for validation of your model
 
+## Ideal Documentation Standards
+
+## Cyberinfrastructure and Tools for Implementation of Documentation Standards
 
+## Examples and References for Documentation