# 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
for" immediately afterward, capabilities, quickstart, and links to the API,
workflows, and scientific contracts.
- README Quickstart contains runnable usage examples and bare `just` for complete
command discovery, with a link to prerequisite setup. CONTRIBUTING owns checks,
fixes, tests, security scans, and PR preparation. Dependency maintenance and
release procedures stay in their focused development and release guides.
Commands that check inputs preserve sources; fix commands declare their writes;
run/example/notebook commands execute a workload. Keep equivalent commands
consistent across research repositories while preserving project-specific
features and arguments. Delaunay's `run` enables its optional `cli` feature;
`examples` discovers the library's examples and their required features.
- `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/delaunay-validation](https://github.com/acgetchell/Papers/tree/main/delaunay-validation)
owns the active manuscript, bibliography, reviewer PDF, pinned figure inputs,
and paper build tooling. `docs/archive/ARTIFACT.md` remains Delaunay's historical
v0.8.0 reviewer artifact guide, with its original release attribution and links.
- `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. `tests/tooling/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 and old design notes;
`docs/archives/changelog/` stores completed minor release series.
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
Active manuscript prose in acgetchell/Papers is author-owned. Preserve its
claims, captions, attribution, and TODOs. Delaunay owns the scientific contracts,
validation notebooks, rendering code, canonical figures, and software tests;
paper builds consume pinned inputs without running those scientific workflows.
## 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/archives/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/archives/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.