The docs are split into User Guide, Examples and API Reference. No rule says what belongs in which, and as a result each section holds a mix. Diátaxis offers a rule: split by what the reader is doing, not by subject. It names four kinds — tutorial, how-to guide, reference, explanation — on two axes: practical vs theoretical, and at study vs at work.
Where we are now
Mapping the 26 hand-written pages onto the four kinds:
| Kind |
Where it actually lives |
| Reference |
api/ (generated by quartodoc) — clean and correct. Also hand-copied into user guide pages. |
| Explanation |
design.qmd; generic.qmd's "When to use / When not to use the generic module"; the flexible-mesh concepts in dfsu.qmd; data-structures.md. All good material, all filed under "User Guide". |
| How-to |
examples/, and also most of mesh.qmd ("Convert mesh to shapely", "Check if points are inside the domain") and dfs0.qmd ("From Dfs0 to pandas DataFrame"). |
| Tutorial |
Nothing. |
The user guide / examples boundary is not defined
examples/Time-interpolation.qmd and user-guide/statistics.qmd are the same shape — headed sections of aggregation and interpolation code against test data — and sit in different sections.user-guide/mesh.qmd is almost entirely task recipes. It is a how-to guide filed as a user guide page.examples/dfsu/merge_subdomains.qmd still reads as the working script it was converted from. Its headings are "Import libraries", "(optional) check first file, items etc.", "choose items to process (when in doubt look at one of the files you want to process with mikeio.open)".
getting-started.qmd holds three kinds at once
Its headings are: Requirements, Installation, Using uv, pip, uv, then Dataset, Types and units, Dfs0, Dfs2, Generic dfs, Additional resources. That is installation instructions (how-to), followed by a whirlwind tour of the API (reference), with no single continuous task anywhere. A newcomer has nothing to follow end to end.
Hand-maintained reference is a second source of truth
The Grid1D/Grid2D property lists (removed in #1051) were copied by hand and nothing kept them in step with the code. Grid2D's list advertises contains(), bbox and xy, which Grid3D does not have (#1050). Generated reference cannot drift this way; prose that restates it can, and does.
Why this is worth fixing beyond tidiness
Structure is what stops content going missing. When the docs moved from Sphinx to Quarto in f4aedf5f, docs/dfs0.md, dfs1.md, dfs2.md and dfs3.md were all deleted; the first three were recreated as .qmd pages and dfs3 was not. dfs3 then had no page at all until #1046 — over two years — while remaining a supported format. Nothing detected it because no rule said every format needs a page in a particular place.
The same absence is why #887 exists: content in the notebooks had no defined home in the docs, so it stayed in the notebooks until the notebooks were removed.
What the current docs get right
Worth stating, because it narrows the work to organisation rather than correctness. I executed every code block on all 26 hand-written pages against the test data:
- all pages run clean, apart from one deliberate
AttributeError demonstration correctly marked #| error: true
- no page uses a deprecated API
- all 71
mikeio.* cross-references resolve
So this is not a correctness problem. It is that a reader cannot tell where to look.
Proposed target
- Write the missing tutorial. One continuous path — open a dfsu, inspect it, subset it, plot it, write it back — that works start to finish with no detours. Split installation out of
getting-started.qmd so the tutorial is not preceded by environment setup.
- Promote Explanation to its own top-level section. Move
design.qmd, data-structures.md, the "when to use the generic module" material, and the flexible-mesh concepts out of the file-type pages.
- Make
examples/ how-to guides, titled by task. "Convert a mesh to shapely", not "Mesh". Move the recipe-shaped sections currently inside the user guide here.
- Keep Reference generated only. No hand-written property lists in prose; link to
api/ instead.
- Record the rule in
CONTRIBUTING.md, so a new page has an obvious home and the split does not drift again. This is the part that prevents a repeat.
Steps 4 and 5 are cheap and independent. Step 1 is the biggest gap for new users. Steps 2 and 3 move ~24 pages and should be agreed before starting.
Related: #887 (content with no Quarto equivalent), #1046, #1051.
The docs are split into User Guide, Examples and API Reference. No rule says what belongs in which, and as a result each section holds a mix. Diátaxis offers a rule: split by what the reader is doing, not by subject. It names four kinds — tutorial, how-to guide, reference, explanation — on two axes: practical vs theoretical, and at study vs at work.
Where we are now
Mapping the 26 hand-written pages onto the four kinds:
api/(generated by quartodoc) — clean and correct. Also hand-copied into user guide pages.design.qmd;generic.qmd's "When to use / When not to use the generic module"; the flexible-mesh concepts indfsu.qmd;data-structures.md. All good material, all filed under "User Guide".examples/, and also most ofmesh.qmd("Convert mesh to shapely", "Check if points are inside the domain") anddfs0.qmd("From Dfs0 to pandas DataFrame").The user guide / examples boundary is not defined
examples/Time-interpolation.qmdanduser-guide/statistics.qmdare the same shape — headed sections of aggregation and interpolation code against test data — and sit in different sections.user-guide/mesh.qmdis almost entirely task recipes. It is a how-to guide filed as a user guide page.examples/dfsu/merge_subdomains.qmdstill reads as the working script it was converted from. Its headings are "Import libraries", "(optional) check first file, items etc.", "choose items to process (when in doubt look at one of the files you want to process with mikeio.open)".getting-started.qmdholds three kinds at onceIts headings are: Requirements, Installation, Using uv, pip, uv, then Dataset, Types and units, Dfs0, Dfs2, Generic dfs, Additional resources. That is installation instructions (how-to), followed by a whirlwind tour of the API (reference), with no single continuous task anywhere. A newcomer has nothing to follow end to end.
Hand-maintained reference is a second source of truth
The
Grid1D/Grid2Dproperty lists (removed in #1051) were copied by hand and nothing kept them in step with the code.Grid2D's list advertisescontains(),bboxandxy, whichGrid3Ddoes not have (#1050). Generated reference cannot drift this way; prose that restates it can, and does.Why this is worth fixing beyond tidiness
Structure is what stops content going missing. When the docs moved from Sphinx to Quarto in
f4aedf5f,docs/dfs0.md,dfs1.md,dfs2.mdanddfs3.mdwere all deleted; the first three were recreated as.qmdpages and dfs3 was not. dfs3 then had no page at all until #1046 — over two years — while remaining a supported format. Nothing detected it because no rule said every format needs a page in a particular place.The same absence is why #887 exists: content in the notebooks had no defined home in the docs, so it stayed in the notebooks until the notebooks were removed.
What the current docs get right
Worth stating, because it narrows the work to organisation rather than correctness. I executed every code block on all 26 hand-written pages against the test data:
AttributeErrordemonstration correctly marked#| error: truemikeio.*cross-references resolveSo this is not a correctness problem. It is that a reader cannot tell where to look.
Proposed target
getting-started.qmdso the tutorial is not preceded by environment setup.design.qmd,data-structures.md, the "when to use the generic module" material, and the flexible-mesh concepts out of the file-type pages.examples/how-to guides, titled by task. "Convert a mesh to shapely", not "Mesh". Move the recipe-shaped sections currently inside the user guide here.api/instead.CONTRIBUTING.md, so a new page has an obvious home and the split does not drift again. This is the part that prevents a repeat.Steps 4 and 5 are cheap and independent. Step 1 is the biggest gap for new users. Steps 2 and 3 move ~24 pages and should be agreed before starting.
Related: #887 (content with no Quarto equivalent), #1046, #1051.