Skip to content

Expand terminology glossary and add CONTEXT.md#652

Open
ecomodeller wants to merge 1 commit into
mainfrom
docs-terminology-glossary
Open

Expand terminology glossary and add CONTEXT.md#652
ecomodeller wants to merge 1 commit into
mainfrom
docs-terminology-glossary

Conversation

@ecomodeller
Copy link
Copy Markdown
Member

Summary

User-facing glossary (docs/user-guide/terminology.qmd):

  • Adds four entries — Field, Geometry type (gtype), Baseline, Quantity — that were either entirely missing or only referenced inside other entries.
  • Reframes Score as primarily a ComparerCollection concept (the cross-observation weighted average is what makes the result a single representative number); Comparer.score is documented as the degenerate single-observation case. Keeps the link target on ComparerCollection.score.
  • Folds Performance into Skill as an alias instead of a separate entry — they were defined as synonyms.
  • Fixes broken links in the Observation entry that pointed to PointModelResult / TrackModelResult instead of PointObservation / TrackObservation.
  • Rewrites Timeseries to contrast point/track (timeseries) with Grid/dfsu (fields) and drop the inaccurate "line, or area" wording.
  • Uses "flexible mesh (dfsu)" when referring to the geometry concept and "dfsu" when referring to the file format. Aligns with mikeio's CONTEXT.md, which is the upstream source-of-truth for this vocabulary. DfsuModelResult (class) stays — it is file-anchored. GeometryType.UNSTRUCTURED (enum) is flagged as legacy in CONTEXT.md but not renamed in this PR.
  • Reorders entries by topic: framing (validation/calibration) → data shapes → matching → assessment → abbreviations.

Adds a dev-facing CONTEXT.md at the repo root:

  • Mirrors the user-facing glossary, organised into Core entities / Geometry types / Skill assessment / Physical quantities.
  • Additionally documents the Vertical alpha vocabulary (VerticalObservation, VerticalModelResult, SkillProfile, cmp.vertical accessor) which is deliberately kept out of the user-facing terminology page until the surface stabilises.
  • Records conventions: z-axis direction (positive="up" default, see MIKE 3 convention), dfsu-vs-flexible-mesh distinction, the skill-vs-score granularity asymmetry, and the legacy UNSTRUCTURED enum name.

Test plan

  • just docs renders without warnings on the new terminology.qmd anchors (#field, #geometry-type-gtype, #baseline, #quantity).
  • Visually inspect the rendered glossary for correct icon/heading display and intra-page links.

User-facing terminology page (`docs/user-guide/terminology.qmd`):
- Add Field, Geometry type (gtype), Baseline, and Quantity as first-class entries.
- Reframe Score as primarily a ComparerCollection concept; Comparer.score is the degenerate single-observation case.
- Fold Performance into Skill as an alias instead of a separate entry.
- Fix Observation links that pointed to ModelResult classes.
- Rewrite the Timeseries entry to contrast with fields explicitly (Grid/dfsu are fields, not timeseries).
- Use "flexible mesh (dfsu)" for the geometry concept; keep "dfsu" for the file format. Aligns with mikeio's vocabulary.
- Reorder entries by topic (framing -> data shapes -> matching -> assessment -> abbreviations).

Add a dev-facing `CONTEXT.md` at the repo root that mirrors the user-facing glossary, additionally documents the Vertical alpha vocabulary that is not yet stable for public docs, and records conventions (z-axis direction, dfsu-vs-flexible-mesh, performance-vs-skill, unstructured enum legacy name).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant