[meta] The Documentation
A lot of improvement has already been done to the documentation with !183 (merged), which restructured the pages in a fairly major way. This meta issue bundles all the documentation-related improvements that have been opened over the years, as well as those that arose in the process of restructuring the docs in !183 (merged). Add and remove points as you see fit.
Incomplete pages (i.e. containing a 'to do')
- Working interactively with Utopia (#210); this also contains a lot of references to the utopya API without linking to them directly, which makes some of them difficult to find. Could this be fixed?
- Handling Data
- Model Documentation/SimpleEG
- Model Documentation/HdfBench
Empty pages
- Usage/workflow
- Implementing models/Nesting Utopia Models
- Performing Simluations/Utopia CLI
Pages requiring modification
1. Tutorial
- The section on plotting uses and refers to the legacy approach (i.e. without the DAG). Is this intentional? If not, perhaps we should update this, to make sure the tutorial nudges users toward the recommended mode of operating.
- The default model configuration for the ForestFire model, included in the tutorial, now contains the validation feature, which is however not mentioned in the tutorial. This could potentially confuse new users – maybe we should add a sentence telling them to just ignore that for now, and focus on the default values?
Related issues: #120, #201, #262
2. Multidimensional Model Runs
Prior to merging !183 (merged), there were a lot of mistakes, some of which I corrected, but I also think it needs more fundamental improvement:
- A lot of important information is hidden away in example configurations: the key information on how to mark a parameter as a
sweep
parameter, for example, is not mentioned in the text. - That there are alternatives to using
range
is also only suggested in an example config – I think this should be explicitly mentioned in the text. - Coupled sweeps are not mentioned. I added a reference, but didn't want to copy-paste a yaml configuration we might be changing anyway (#267 and #266 are related to this), so I've just linked to the feature list.
- The text doesn't mention that, instead of setting
universes: all
in the plot config, specific universes can be chosen. - There is a warning on the page stating that many more features have been added that are not mentioned in the text. Perhaps the text should elaborate a little more on the core plotting capabilities, with corresponding links the to the plotting page.
3. Model documentations
- Many of the model documentations still contain references to the CCEES lecture notes. I haven't removed them, but I'm guessing we should? This applies to: ContDisease, FFM, PredatorPrey, SandPile, PredatorPreyVegetation. @JulianWeninger Your BSc thesis is referenced in the Geomorphology model documentation, though I assume it is not publicly available. Can you provide a public link to your thesis?
Related issues: #191 (CopyMe models), #239, #289 (closed).
4. Further proposed improvements, changes, and extensions
- Remove further references to the CCEES lecture notes in the Step-by-step guide.
- #24: FAQ-related
- #39: Document the dataI/O backend
- #74: Correctly document WriteMode
-
#130: Improve the
apply_rule
documentation - #254 (minor): README improvements
- #267: Documentation of config files
- #269: Document how to write out AgentManager data with varying number of agents
Edited by Thomas Gaskin