Tutorial First Documentation Change

Tutorial: First Documentation Change

Outcome

You will make one small documentation change using the project's split documentation system (wiki + rustdoc + docs/ artifacts), run the required validation commands, and understand how to record the external wiki commit correctly for a pull request.

Observable outcome:

• a small documentation edit exists in the correct location for its intent
• wiki/docs validation commands complete successfully
• if the wiki was edited, you can identify the external wiki repository change and record its branch/SHA in review notes

Entry Criteria

Prior Knowledge

• basic git and terminal usage
• recommended: complete Tutorial: Run the Prototype Locally
• recommended: complete Tutorial: Trace a Desktop Action End to End

Environment Setup

• repository checkout available locally
• terminal opened at the repository root (/Users/justinshort/os)
• external wiki checkout available (or create it during this tutorial)

Dependencies

• Rust toolchain installed (for docs validation commands)
• a small documentation change to make (wording fix, link correction, example tweak, registry/index adjustment)

Procedure

Step 1: Classify the change by documentation intent

Open Home and choose the correct documentation surface for your change:

• wiki page under wiki/ for tutorials/how-to/explanations/reference indexes/navigation
• Rust source comments for API behavior (rustdoc)
• docs/adr/* or docs/sop/* for formal decisions/procedures

If your change is about exact artifact inventory or canonical locations, confirm the target reference page under Reference.

Step 2: Confirm the external wiki checkout state

cargo wiki status

If the external checkout is missing locally and you are not already carrying wiki edits, create it with:

cargo wiki clone

This ensures the wiki checkout is present and visible before you edit wiki pages.

Step 3: Make one small documentation edit in the correct place

Examples:

• fix wording or navigation in a wiki page under wiki/
• improve or correct rustdoc item comments in the affected crate
• update a formal artifact in docs/adr/* or docs/sop/*

Keep the change small and intentional so you can focus on workflow discipline rather than content volume.

Step 4: Update or verify the relevant wiki index/registry (when required)

If your change adds or materially changes a formal artifact, update the corresponding wiki index page.

Examples:

• artifact inventory/navigation changes -> Reference: Documentation Artifact Registry
• ADR changes -> Reference: Architecture Decision Records
• SOP/runbook changes -> Reference: Operational Runbooks and SOPs

Step 5: Run documentation validation

cargo xtask docs wiki
cargo xtask docs all
cargo doc --workspace --no-deps
cargo test --workspace --doc

If your change did not touch rustdoc, the cargo doc and doctest steps are still useful practice in this tutorial because they demonstrate the full documentation workflow.

Step 6: Inspect the resulting change state

If you edited wiki content, inspect the external wiki repository and then the main repo:

git -C ../os.wiki status --short
git status --short

This shows the wiki page edits in the external checkout and the separate main-repo state.

Validation

Confirm the tutorial is complete only when all items below are true:

1. The documentation change is stored in the correct surface for its intent.
   • Expected result: wiki navigation/routing content is in wiki/; API semantics are in rustdoc; ADR/SOP content is in docs/.
2. cargo xtask docs wiki exits with code 0.
   • Expected result: xtask prints OK.
3. cargo xtask docs all exits with code 0.
   • Expected result: xtask prints OK.
4. cargo doc --workspace --no-deps completes successfully.
   • Expected result: docs build without fatal rustdoc errors.
5. cargo test --workspace --doc completes successfully.
   • Expected result: doctests pass or report no failures.
6. If wiki content changed, git -C ../os.wiki status --short shows the modified page(s).
   • Expected result: the changed wiki file is listed.

Next Steps

• Move to the task-oriented PR workflow: How to Update Documentation in a Pull Request
• Review the project-wide documentation maintenance rules: Contributing Standards (Code + Docs + Wiki)
• Understand the documentation system rationale: Explanation: Documentation Architecture and Governance
• Look up canonical artifact locations: Reference: Documentation Artifact Registry