# Documentation Guidance
Documentation, changelog, citation, and scientific-notation rules for this
repository.
---
## Contents
- [Documentation Ownership](#documentation-ownership)
- [Navigation and Ordering](#navigation-and-ordering)
- [Filenames and Renames](#filenames-and-renames)
- [Academic Paper Authorship](#academic-paper-authorship)
- [Scientific Notation](#scientific-notation)
- [References](#references)
- [Changelog Maintenance](#changelog-maintenance)
- [Crates.io Documentation](#cratesio-documentation)
---
## Documentation Ownership
- `README.md` owns evaluation and getting started: introduction, "Use this crate
when" immediately afterward, capabilities, quickstart, and links to the API,
workflows, and scientific contracts.
- `REFERENCES.md` owns bibliographic records, stable citation keys/anchors, and
a concise topic-to-source index. Keep derivations and caller contracts in
their topic guides; retain brief implementation/background attribution.
- `docs/scientific_basis.md` owns the scientific overview: early API selection
and geometry/topology scope, shared assumptions, method summaries, and links
to existing detailed contracts and specific sources. Do not copy entire
guides into the overview.
- `AGENTS.md` is the coding-agent entry point.
- `docs/dev/README.md` indexes development workflow guidance.
- `docs/dev/notebooks.md` owns notebook cell identity, execution, and artifact
policy.
- `docs/code_organization.md` is the required-reading architecture hub.
- `docs/construction_and_validation.md` owns proof-bearing construction
vocabulary, promotion boundaries, validation levels, and validation-policy
guidance.
- `docs/architecture/README.md` indexes focused architecture references.
- `CITATION.cff` owns citation metadata.
- `papers/*.tex` owns publication-facing mathematical exposition. The matching
`papers/*.bib` files own paper-local BibTeX references. The matching
`papers/*.pdf` files are tracked reviewer copies, built from TeX in
`target/papers/` with Tectonic and refreshed by `just papers` or
`just paper-refresh`.
- `docs/assets/validation/*.png` owns stable validation figures generated by
notebooks and reused by both documentation and papers. Regenerate them with
`just validation-doc-figures`; ordinary notebook checks write only under
`target/notebooks/`.
- `README.md`'s first Introduction paragraph and `CITATION.cff`'s `abstract`
field intentionally mirror each other. When one changes, update the other in
the same patch. `scripts/tests/test_readme_citation_mirror.py` checks the
normalized text after Markdown links are stripped from the README prose.
Semgrep also rejects stale public validation-hierarchy wording.
- `docs/archive/` stores historical plans, completed changelog series, and old
design notes. Do not update archived docs as active guidance unless an
explicit archive-maintenance task asks for it.
## Navigation and Ordering
Keep Contents links current in the README, bibliography, scientific overview,
and other documents with Contents sections. Put API selection and scientific
scope before shared assumptions and method discussions in the overview.
Sort independent algorithm/method headings lexicographically within coherent
groups. Keep prerequisites before dependent explanations and derivations under
their method. Do not alphabetize validation levels, execution steps, release
chronology, or bibliography themes. Sort introductory/capability bullets only
when their order carries no meaning. Retain existing citation identifiers and
heading fragments; use compatibility anchors when a heading must change.
The README is included verbatim in rustdoc. Use explicit repository URLs for
learning documents, with `main` for active guides and the declared release tag
for release-owned files. Use docs.rs for API destinations. New or renamed paths
must target a revision containing them, never an older release tag. Local work
can verify the future tree, but links to new `main` paths become public only
after the changes land. Check exact filename case and fragment targets in both
GitHub-compatible rendering and generated rustdoc. Prefer explicit ASCII
anchors when emoji or punctuation produce different renderer slugs.
## Filenames and Renames
Classify active Markdown throughout `docs/`, including subdirectories, by its
primary purpose:
- Task guides with execution instructions use uppercase verbs or verb phrases,
preferably gerunds: `RELEASING.md`, `USING_TRIANGULATIONS.md`, and
`dev/TUNING-PERFORMANCE.md`.
- Discussions of invariants, principles, policy, architecture, reference
material, analysis, and results use lowercase descriptive names. A performance
report is `performance.md`; tuning instructions belong in a task guide.
A few command examples do not make a reference or policy document a task guide.
- Keep conventional directory `README.md` indexes, standard root filenames,
historical archive paths, and each area's existing hyphen/underscore style.
Record old-to-new paths and classification rationale in the change description.
Update navigation, ownership maps, source comments, generators, configured output
paths, and relevant checks together. On case-insensitive filesystems, use an
intermediate filename for a case-only rename and verify the final directory entry.
Preserve generated measurements and provenance byte-for-byte when only moving a
report. Update its generator for future output; regenerate affected generated
navigation through its owner. Human-maintained indexes and architecture trees
are edited with the rename. Renaming alone does not require fresh benchmarks or
manual edits to historical archives.
## Academic Paper Authorship
Paper prose under `papers/` is author-owned. Agents must not add substantive
publication prose there. They may maintain outlines, TODO scaffolds, TeX/build
tooling, figures, citations, and review comments.
Keep paper drafts visibly marked as outlines or TODO scaffolds until the
maintainer supplies prose. Treat formal AI-use disclosure as a separate
venue/submission matter, not as a repository guidance claim.
## Scientific Notation
Unicode math is welcome in doc comments and active documentation when it makes
scientific meaning clearer. Examples include:
```text
×, ≤, ≥, ∈, Σ, ², 2^-50, χ(S^d) = 1 + (−1)^d
```
Prefer mathematical invariants where possible instead of prose-only
descriptions.
Use topological-space notation when naming a fixed manifold. Write `T^2`,
`T^3`, `S^2`, or `S^3` in prose and doc comments; Unicode superscripts such as
`T²` and `S²` are equivalent. Rust identifiers use `t2`, `t3`, `s2`, and `s3`.
Keep labels such as `2D` and `3D` for algorithm, coordinate, ambient, or
simplicial-complex dimensions. For example, describe a cone over `T^2` as a 3D
simplicial complex rather than calling its torus link "2D" or "3D."
## References
Algorithms should cite their sources in `REFERENCES.md` and document relevant
conditioning behavior. Typical references include Shewchuk, Bowyer-Watson,
Edelsbrunner, and Preparata-Shamos.
Use numbered `REFERENCES.md` citations in API docs and active design docs when
describing algorithms, numerical robustness, or topology guarantees.
## Changelog Maintenance
- Never edit `CHANGELOG.md` or `docs/archive/changelog/*.md` manually.
- Run `just changelog` to regenerate the root changelog and archive files from
commits.
- The root `CHANGELOG.md` contains only `Unreleased` plus the active minor
series.
- Completed minor series are archived in `docs/archive/changelog/X.Y.md`.
Commit-message rules that affect generated changelog text live in
[`git.md`](git.md).
## Crates.io Documentation
Publish documentation changes before bumping the crates.io version. crates.io
does not allow re-publishing documentation without a version bump.