Documentation · Compass
996102e0
Documentation compass
Choose the route that matches what you are trying to do right now. The same topic may appear in more than one documentation type because learning a workflow, completing a task, looking up an exact contract, and understanding the reasoning are different needs.
This structure is adapted from the tutorial / how-to / reference / explanation separation described by Diátaxis. GazeAudit keeps its existing public sections, but makes their intended use explicit instead of renaming every page.
Build confidence by doing
Use a small synthetic or guided workflow when the goal is to learn how the pieces fit together.
Complete a research task
Use goal-oriented guidance when you already have a study, decision, reviewer request, or blocked workflow to handle.
Find an exact fact or contract
Use reference material when the question is factual: a function signature, CLI command, denominator term, source revision, or frozen authority.
Understand why the system is structured this way
Use conceptual material and bounded case studies when the goal is interpretation, rationale, or methodological context rather than a procedure.
One topic can legitimately have several routes
For specification-space robustness:
| Need | Route |
|---|---|
| Learn the sequence on deterministic data | End-to-end robustness example |
| Apply the method to a research decision | Specification-space guide |
| Look up the public function contract | run_specs API pathway |
| Understand why one pipeline is insufficient | From one pipeline to a robustness audit |
| Inspect the empirical boundary | Case studies |
For controlled sensitivity analysis:
| Need | Route |
|---|---|
| Learn the sequence on deterministic data | Sensitivity protocol example |
| Design the study-specific perturbation protocol | Sensitivity-analysis design guide |
| Structure the analysis as a study-level layer | Sensitivity-audit workflow |
| Look up sampling, missingness, or spatial-sensitivity functions | API pathways |
| Understand why the curve is not an optimisation search | Sensitivity is not a search |
| Choose a reproducible visual | Plot gallery |
The pages are related, but they should not collapse into one giant page. Reference stays factual; how-to guidance stays task-oriented; teaching examples remain explicit about synthetic choices; conceptual pages can explain rationale without pretending to be executable instructions.
If you are blocked
Use the intent that best matches the blocker:
- I do not know how the workflow works → start with Learn.
- I know what I need to accomplish → use Do.
- I need exact syntax, terminology, or provenance → use Look up.
- I need to understand the rationale or evidence boundary → use Understand.
If the problem is a failure rather than a documentation-choice problem, go directly to Troubleshooting GazeAudit.
Search is a second route
Use Ctrl/Cmd + K when you already have useful words such as run_specs, AOI uncertainty, technical_failure, or revision package. Search results are grouped by documentation type so you can choose the kind of answer you need rather than treating ranking as a scientific recommendation.
For a worked exercise, continue to Documentation intent routing.