# Documentation Plan (User-Facing Docs Roadmap)

Last updated: 2026-02-25

## 1) Goal

Make ASTRODYN-CORE easy to learn and adopt for humans (not only code-reading LLMs)
by shipping a documentation system that supports:

- fast "time to first propagation"
- task-based learning (tutorials and recipes)
- discoverable API reference
- troubleshooting and environment guidance (Orekit/JVM/C++ build)
- contributor-facing extension docs for advanced users

## 2) Current state (baseline)

What already exists:

- Strong `README.md` for install/test/status overview
- Working example scripts in `examples/`
- Cookbook scripts in `examples/cookbook/`
- Several architecture/implementation plans in `docs/`
- Good tests and example artifacts (`examples/generated/`)

Main gaps for human users:

- No docs site / navigation hierarchy
- Examples are scripts, not guided tutorials
- API reference is not generated from docstrings
- Inconsistent discoverability across subsystems (propagation, states, mission, uncertainty)
- Missing troubleshooting docs (Orekit data, JVM bridge, C++ wheels/builds, credentials)

## 3) Audience and documentation jobs-to-be-done

Primary audience (v1.x):

- Python users who want to propagate orbits quickly using Orekit-backed workflows
- Analysts who want reproducible scenario/state-file pipelines
- Engineers evaluating GEqOE / analytical-vs-numerical options

Secondary audience:

- Advanced Orekit users extending providers
- Contributors modifying internal modules or adding features

What users need to do:

- install and verify the environment
- run a first propagation end-to-end
- choose the right API tier (facade vs advanced)
- configure force models, spacecraft, and build context
- work with state files and mission timelines
- run uncertainty workflows
- troubleshoot common setup/runtime issues

## 4) Documentation architecture (recommended structure)

Use a docs site with four layers:

1. Getting Started (beginner path)
- Install
- Environment setup (`astrodyn-core-env`)
- Orekit data setup
- First propagation in 10 minutes
- How to run examples

2. Tutorials (guided, sequential, task-based)
- Propagation quickstart (facade-first)
- Scenario/state-file workflow
- Mission execution (intent + detector)
- Uncertainty covariance propagation
- GEqOE tutorial (when/why/how)

3. How-to / Cookbook (goal-oriented recipes)
- "How do I choose a propagator kind?"
- "How do I add force models?"
- "How do I parse OEM and build ephemeris propagation?"
- "How do I compare numerical vs DSST vs Keplerian?"
- "How do I export/import state series?"

4. Reference (generated + curated)
- API reference (autogenerated from docstrings)
- Configuration/schema reference (specs, models, YAML structures)
- Example index (script catalog with inputs/outputs)
- Troubleshooting and FAQ
- Architecture/extension docs (advanced)

## 5) Tooling recommendation

Recommended stack:

- `MkDocs` for docs site generation
- `mkdocs-material` for theme/navigation/search
- `mkdocstrings[python]` for API reference from docstrings
- `mkdocs-gen-files` (optional) to auto-generate API pages
- `mkdocs-literate-nav` (optional) for scalable nav management

Why this stack:

- lower setup and maintenance overhead than Sphinx for a Python-first project
- easy Markdown authoring for tutorials/how-to guides
- good search/navigation UX out of the box
- straightforward CI build later

Deferred (optional later):

- notebooks rendered in docs (`mkdocs-jupyter`) if interactive tutorials become important
- diagrams-as-code integration (Mermaid/PlantUML)

## 6) Content plan (what to write first)

### Phase 1: MVP docs for user onboarding (highest ROI)

Deliverables:

- `docs-site/index.md` (landing page)
- `docs-site/getting-started/install.md`
- `docs-site/getting-started/orekit-data.md`
- `docs-site/getting-started/first-propagation.md`
- `docs-site/getting-started/examples.md`
- `docs-site/troubleshooting/common-setup-issues.md`

Definition of done:

- A new user can install, run one propagation, and understand next steps without reading source code.

### Phase 2: Tutorial track (convert scripts into guided docs)

Convert current scripts into tutorial pages with narrative context, expected outputs,
and decision guidance.

Priority tutorial mappings:

- `examples/quickstart.py` -> "Propagation tutorial"
- `examples/scenario_missions.py` -> "Scenario + mission workflows"
- `examples/uncertainty.py` -> "Covariance and STM workflows"
- `examples/geqoe_native/geqoe_propagator.py` -> "GEqOE propagator usage"

Each tutorial page should include:

- learning goals
- prerequisites
- minimal runnable code
- explanation of key objects (`AstrodynClient`, `BuildContext`, `PropagatorSpec`, etc.)
- expected outputs/files
- common mistakes
- "next tutorial" links

### Phase 3: Cookbook / how-to guides

Promote `examples/cookbook/*.py` into docs pages with shorter, focused recipes.

Priority topics (based on current examples):

- multi-fidelity comparisons
- force model sweep / degree-order choices
- OEM ingestion and ephemeris workflows
- SMA maintenance analysis
- orbit conversion validation

### Phase 4: API reference and docstring coverage

Generate API docs from docstrings, starting with stable public surfaces:

- `astrodyn_core` root exports
- `propagation` facade/specs/interfaces
- `states` client and I/O entry points
- `mission` client and timeline execution entry points
- `uncertainty` client and propagation entry points
- `ephemeris`, `tle`, and `orekit_env` public helpers

Docstring focus order:

1. Public facades and top-level functions
2. Typed specs/models used in examples/tutorials
3. Advanced factory/registry/provider interfaces
4. Internal modules only when needed for contributor docs

### Phase 5: Advanced/reference docs and extension guidance

Curate and refine:

- provider extension guide (existing docs + examples)
- GEqOE architecture/performance notes
- advanced Orekit-native usage patterns
- internal architecture map (module boundaries and responsibilities)

## 7) Example-to-doc conversion standard (important)

Current example scripts are useful but hard to learn from without narrative.
Each promoted example should become a docs page plus a verified runnable script.

Policy:

- Keep scripts as executable truth (regression/smoke value)
- Add docs pages that explain the script instead of replacing the script
- Prefer shorter tutorial snippets over pasting entire scripts
- Link to exact script path and generated output artifacts

Recommended docs metadata for each example page:

- purpose
- API tier used (facade vs advanced)
- runtime requirements (Orekit data, credentials, optional deps)
- approximate runtime
- outputs written under `examples/generated/`

## 8) Multi-LLM workflow (safe way to scale docstrings/docs)

Using multiple small LLMs is a good idea, but use strict guardrails.

### Guardrails

- Define one docstring style and enforce it (Google or NumPy style; pick one)
- Limit LLM tasks to documentation-only changes unless explicitly approved
- Require code behavior to remain unchanged
- Run tests after each batch
- Human review public API docstrings before merge

### Recommended execution model

Use one orchestrating pass + many small scoped passes:

1. Orchestrator creates inventory of public APIs (by package)
2. Worker LLMs patch docstrings in small batches (one package at a time)
3. Orchestrator runs tests + style checks + docs build
4. Human reviews accuracy/tone and merges

Suggested batch order:

- Batch A: `orekit_env`, root exports, `propagation.interfaces/specs`
- Batch B: `propagation.client/factory/registry`
- Batch C: `states` public entry points
- Batch D: `mission` and `uncertainty` public entry points
- Batch E: `ephemeris` and `tle`

### What LLMs should NOT do initially

- Rewrite internal implementation comments en masse
- Document every private helper before public APIs are covered
- Introduce examples in docstrings that are untested
- Change signatures/types while "improving docs"

## 9) Documentation style guide (minimum rules)

Create `docs/docstring-style.md` and enforce these basics:

- Describe behavior and intent, not obvious syntax
- Use parameter names exactly as in code
- State units explicitly (meters, seconds, radians, UTC, etc.)
- Call out Orekit/JVM requirements where relevant
- Include short runnable examples only for stable public APIs
- Keep internal/private docstrings minimal unless behavior is subtle

For user-facing docs pages:

- Start with "what this solves"
- Show the shortest working path first
- Add advanced options later in the page
- Include troubleshooting notes near failure-prone steps
- Link related tutorials/how-to pages

## 10) Validation and maintenance plan

Documentation should be treated like product surface area.

Minimum checks (initially local, later CI):

- docs site builds successfully
- no broken internal links
- code snippets are syntactically valid (where practical)
- example paths referenced in docs exist
- API reference generation succeeds

Recommended later CI jobs:

- `mkdocs build --strict`
- link checker (internal + external, maybe scheduled)
- smoke run of a small subset of examples

## 11) Proposed repository changes (next implementation step)

When you are ready to implement the docs system, do this in one focused PR:

1. Add docs site scaffold (`mkdocs.yml` + `docs-site/`)
2. Add `docs/docstring-style.md`
3. Add MVP Getting Started pages
4. Add tutorial pages for `quickstart.py` and `scenario_missions.py`
5. Add API reference scaffold (even if incomplete)
6. Add `make docs-serve` and `make docs-build` shortcuts

## 12) Success criteria (v1.x docs initiative)

The documentation effort is successful when:

- A new user can reach first propagation in under 15 minutes
- Core workflows are documented as tutorials, not only scripts
- Public APIs have generated reference pages from docstrings
- Common setup/build/Orekit issues are documented
- Examples and docs remain aligned through routine maintenance

## 13) Immediate next actions (recommended)

1. Approve docs tooling stack (`MkDocs` + `Material` + `mkdocstrings`)
2. Approve docstring style (`Google` or `NumPy`)
3. Scaffold docs site and MVP Getting Started pages
4. Run first docstring batch on public `propagation` and `orekit_env` APIs
