Problem
The generated schema documentation at https://isamples.org/metadata/ is overwhelming for newcomers. After the one-paragraph schema description, the page jumps immediately into a flat, alphabetical Classes table where `MaterialSampleRecord` (the centerpiece) sits as an equal sibling to supporting concepts like `IdentifiedConcept` and `Agent`.
There is no narrative explaining how the classes relate — specifically:
- that `MaterialSampleRecord` is the core record,
- that `SamplingEvent` / `SamplingSite` / `GeospatialCoordLocation` describe the act of sampling that produced it,
- that `MaterialSampleCuration` and `SampleRelation` describe what happens to it after sampling,
- that `Agent` and `IdentifiedConcept` are supporting types used across the model.
Proposal (v0.1, low-risk)
Add a hand-written "How this schema is organized" section to `tools/docgen/index.qmd.jinja2` between `{{ schema.description }}` and the autogenerated `## Classes` table. A few short paragraphs grouping the 8 classes semantically, with inline links to each class page. The autogen tables stay below as the complete reference.
Tradeoff: the narrative lives in the template and won't auto-update when new classes are added to the LinkML schema — someone needs to revise it. Acceptable for a schema that changes infrequently.
Future work
- Consider a visual class-relationship diagram (the `class_overview_diagram.qmd.jinja2` include already exists but is minimal).
- Eventually: LinkML-level tags/subsets that let the generator group classes automatically.
Problem
The generated schema documentation at https://isamples.org/metadata/ is overwhelming for newcomers. After the one-paragraph schema description, the page jumps immediately into a flat, alphabetical Classes table where `MaterialSampleRecord` (the centerpiece) sits as an equal sibling to supporting concepts like `IdentifiedConcept` and `Agent`.
There is no narrative explaining how the classes relate — specifically:
Proposal (v0.1, low-risk)
Add a hand-written "How this schema is organized" section to `tools/docgen/index.qmd.jinja2` between `{{ schema.description }}` and the autogenerated `## Classes` table. A few short paragraphs grouping the 8 classes semantically, with inline links to each class page. The autogen tables stay below as the complete reference.
Tradeoff: the narrative lives in the template and won't auto-update when new classes are added to the LinkML schema — someone needs to revise it. Acceptable for a schema that changes infrequently.
Future work