docs: Diátaxis documentation overhaul - #404
Merged
Merged
Conversation
Point fixes from the Diátaxis docs audit (notebook 006), each verified against the code before editing: - CLI reference: remove phantom --recreate, add real --scene flag - robot/docker: ROBOT_LAUNCH_PACKAGE/FILE -> real LAUNCH_PACKAGE var - Replace nonexistent airstack_msgs types (TrajectorySegment, TrajectoryOverride) with TrajectoryXYZVYaw in doc standards, AGENTS.md - Fix dead local/c_controls path -> local/controls (AGENTS.md, agent guide) - pegasus_scene_setup: .env snippet now matches actual .env defaults - scenes.md: fetch_scene.sh example uses a real key (blocks) - Testing docs: add missing wiring/waypoint_flight marks; drop false 'autonomy mark unregistered' troubleshooting row - Getting Started: Move Robot step updated to the auto-seeded Foxglove layout flow (+ host port 8766 note); requirements canonicalized (RTX 3070 min / 4080 rec, 100GB free disk, Ubuntu 22.04/24.04) and aligned in docs/README.md and about.md - OSMO positioning reconciled: recommended REMOTE path; local Linux+GPU remains the golden path - tasks.md + interface conventions spec reconciled to the eight task_msgs actions (spec bumped to v1.0.1 per its changelog rules) - perception index outputs corrected to spec (odometry_conversion/odometry) - exploration README: fix random-walk copy-paste; vscode_debug: per-container .devcontainer layout; docker_usage: retire pre-harness 'Automated Testing' section, fix subnet, drop dead Isaac streaming refs - Remove deprecated Ascent extension from simulation Getting-Started list Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Deletes the superseded/orphaned stratum found by the audit: - docs/tutorials/index.md (zero inbound links; duplicate of tutorials_reference.md) - docs/development/development_environment.md and docs/development/airstack-cli/index.md (stale orphaned twins of the in-nav beginner/ versions) - docs/development/intermediate/testing/testing_frameworks.md (pre-harness taxonomy, broken example; inbound links repointed) - docs/simulation/isaac_sim/scene_setup.md and ascent_sitl_extension.md (Ascent-era pipeline; nav entry removed) plus six images referenced only by them frame_conventions.md rewritten from live facts: the world->map static identity TF in autonomy_bringup robot.launch.xml and the canonical TF table in the interface conventions spec. (scene_setup's map_FLU 90-degree-rotation story matched nothing in the code.) mkdocs-redirects entries added for all six removed URLs. git-hooks READMEs rewritten as deprecation notices: the docker-versioning hook writes a commit hash into .env VERSION, which the semver check-version-increment gate rejects; note left that 'airstack config git-hooks' still installs it (CLI removal is a follow-up code change). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adds seven documents that existed only as off-site READMEs to mkdocs.yml (served via the same-dir plugin, like the stack READMEs): - config/vehicles/README.md — the vehicle.yaml schema (fleets.md now links it relatively instead of via GitHub URL) - config/local/README.md — the CALIBRATION_DIR unit-calibration contract - common/module_schema/README.md — the authoritative module.yaml field/validation reference, under the Modules section - robot/ros_ws/src/sensors/lidar_point_cloud_filter/README.md — the only full-quality robot package README that was not in nav - common/ros_packages/gui/rviz/rviz_tasks_panel/README.md and 3d_waypoint_rviz2_plugin/README.md — operator manuals for the task and waypoint panels - osmo/README.md — the OSMO lab-admin half of the OSMO story, complementing the student tutorial Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
mkdocs.yml nav reorganized into Tutorials / How-to Guides / Reference / Concepts tabs (plus Home, Release Notes, About), with product areas as second-level groups inside each tab. No files move — nav labels only — so every page keeps its URL. This also restores the repo's own 3-level nav-depth rule (the old Robot tree reached 5 levels). The mislabeled Beginner/Intermediate/Advanced 'Tutorials' buckets are gone: the Development section contained zero tutorials (all how-to, reference, and explanation content, now filed by type). Two hub pages rewritten for the new shape: - getting_started/tutorials_reference.md — quadrant-honest 'What Next' page (by-goal table + persona paths) replacing the level-labeled catalog that called reference/explanation pages tutorials - development/index.md — How-to Guides landing (guide groups + the handful of daily commands, deferring tables to the CLI reference) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
One canonical home per fact; clones replaced with links (net -131 lines):
- Topic/interface tables -> interface_conventions.md spec:
robot/index.md keeps 3 labeled examples; integration_checklist.md's
~110-line drifted reference block (incl. nonexistent interface/cmd_vel)
replaced with deep links into spec sections (anchors verified against
the rendered toc)
- airstack up flags -> CLI reference: docker_usage, key_concepts, and
the Getting Started launch tail keep 2-3 examples + a link
- pytest marks -> tests/README.md: testing/index.md table replaced with
a summary + link; ci_cd.md keeps its table for the CI-cost narrative
but now cites tests/README.md as authoritative
- scene_prep.py helpers -> spawning_drones.md (richer copy); pegasus
page links it via a stable {#scene-prep-helpers} anchor
- modular_airstack.md: duplicated setup section replaced with its own
prerequisite pointer; redundant -f docker-compose.modules.yaml flag
removed (airstack.sh auto-includes it, verified cmd_up/cmd_down)
- MS-AirSim pair merged: index.md owns overview/quickstart/settings/
topics/user troubleshooting; docker.md owns container internals.
Ground truth from entrypoint.sh: BOTH pages had the tmux ordering
backwards (bridges are windows 1..N, PX4 N+1..2N, named
robot_<i>_bridge / robot_<i>_px4); port table corrected to
4560+i / 24540+i / 24580+i per settings.json.j2, and the wrong
MAVLink-port troubleshooting bullet fixed
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Four splits from the audit's Phase-3 list (originals keep their URLs; new pages added to nav): - system_architecture.md (643 -> ~375 lines): keeps the explanation core (node types, task cascade, layer table, communication patterns, multi-robot); per-layer topic lists (a drifted 4th copy of spec data) replaced with layer-index + spec links; the data-flow diagram now matches the real action cascade (results return to the action client, not a Behavior node); invented Performance Characteristics deleted; integration guidelines deferred to the checklist - ci_cd.md -> ci_cd.md (maintainer explanation: architecture, cache, security, pod anatomy) + NEW using_ci.md (developer how-to: triggering, /pytest syntax, marks/cost, reading results, user-facing troubleshooting); 18 absolute blob/main links converted to relative - foxglove.md -> operator page + NEW extending_foxglove.md (the 6-step marker-type recipe and visualizer-source guidance) - isaac_sim/docker.md (459 -> 193 lines, pure container reference) + NEW container_workflows.md (launch modes, credentials, access, dev workflow, image management, troubleshooting); verbatim compose quoting trimmed to excerpts; two placeholder sections folded away Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Rewrites of pages whose content was fictional, generic filler, or contradicted the code (net -600 lines of invented material): - global/planning/index.md: never-built Global-Manager/PlanRequest protocol (live TODO markers included) replaced with the shipped architecture: task-executor action servers -> global_plan handoff, verified against tasks.md, spec sections, and both planner sources (toggle attributed only to exploration — random_walk declares the remap but never serves it) - interface/index.md: hotlinked placeholder diagram replaced with a verified mermaid of the real command/state flow; State section corrected — canonical odometry + map->base_link TF come from the odometry_conversion node, not RobotInterface; both TODOs gone - configuration/index.md (369 -> 96 lines): fabricated config YAML, invented validation script, and generic Linux/Jetson sections deleted; keeps verified stack selection, env vars, identity pointer, and a new where-config-actually-lives table - rosbags.md (210 -> 86): generic ros2-bag tutorial cut to a link; fake bag-info output removed; BAG_STORAGE_PATH documented - logging/data_offloading.md (323 -> 23): gutted to a pointer at the real storage-tools workflow with one honest rsync one-liner using real bag paths (the old /opt/airstack paths exist nowhere) - HITL/index.md rewritten for the current stack: gcs-real hitl profile, l4t launch, domain-ID alignment and fastdds.xml, honest unverified-caveats for cross-machine DDS and sim-SITL FCU paths, Foxglove-based verification (RViz-era steps gone) - Six layer-index stubs filled to a uniform template (role, child links, stack-launch note, spec-linked interchanges): autonomy front door, local, global, global/world_model, static_transforms, behavior (first paragraph no longer contradicts the page) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
New documents for surfaces that had none, every claim verified in code: - Environment Variables reference (docs/robot/configuration/ environment_variables.md): the complete .env schema — every uncommented var with default and verified consumer, plus the variables exported by airstack up flags and the notable optional vars - airstack_msgs README (nav-linked under Reference -> Interfaces): all 10 messages + 4 services with field tables; unused types marked 'defined; no trunk consumer' honestly; found PlanToWaypoint.srv is not in rosidl_generate_interfaces (never built) — documented as such - trajectory_library README (replaces the 6-line in-nav TODO stub): classes, the YAML config schema from the parser (degrees conversion, $(param) substitution), real config excerpts; corrects the assumption that droan_gl loads the YAML (it only links the classes) - Supported-platform matrix (docs/real_world/supported_platforms.md): honest statuses — CI-tested only for desktop x86 sim; Orin field-used per install guide; VOXL 'profile exists, docs in progress' - Deploying to Hardware rewritten from its TODO skeleton into a real 8-step tutorial (identity, FCU serial, stack choice, props-off bench test, HITL rehearsal, first-flight checks) with per-step checks and hardware-verify notes where the repo can't confirm specifics; nav entry promoted to the Tutorials tab - Operating the GCS (rewrites the 23-line user_interface.md stub): panel walkthrough verified from the seeded layout JSON and the robot-commands extension bundle (7 task tabs; explicitly notes the Foxglove panel lacks the RViz panel's airborne gating) - robot/docker/index.md base-image rows updated to current compose values (ubuntu24.04 / dustynv jazzy r36.4.0) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Updates the doc-authoring standards so the new structure stays clean: - documentation.md: the three-type taxonomy (Tutorials/Guides/Reference) replaced with the four Diátaxis quadrants plus a decision tree for choosing the kind of a new page; package READMEs stay exempt (intentionally all-in-one) - contributing.md: Documentation section now names the quadrant rule and links the decision tree; docs commands unified on airstack docs - write-mkdocs-documentation skill: the beginner/intermediate/advanced organization pattern (the root cause of the old mislabeled nav) replaced with the quadrant-tab layout; nav example updated - update-documentation skill + AGENTS.md: mkdocs nav examples updated to the new Reference -> Autonomy Packages shape; AGENTS.md points at the decision tree Release flow per bump-version-and-release: VERSION 0.20.0-alpha.14 -> 0.20.0-alpha.15 (regex-validated), with a Documentation Overhaul entry added to the 0.20.0 (Unreleased) release-notes section summarizing the restructure, the 18 accuracy fixes, removals/redirects, rewrites, splits, newly surfaced references, and the interface-spec v1.0.1 bump. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
New guides (every command/topic verified in code, each offering the in-tree package vs 'airstack module create --in-tree' scaffolding choice per the module workflow): - Adding a State Estimator (perception): conform to spec §2, swap via the interface_odometry_in_topic launch arg in a stack entry (the odometry_conversion node owns the canonical topic and map->base_link TF, launched unconditionally); asm_macvo as the module precedent - Adding a Planner: local (DROAN pattern, §5 surface; verified swap example from full_droan_cpu) and global (task-executor pattern, random_walk); flight verification via -m waypoint_flight since -m autonomy never exercises tasks/navigate - Creating a Multi-Agent Coordination Algorithm: gossip/PeerProfile bus (peer_registry over raw /gossip/peers, QoS verified), honest platform-gaps section from the coordination README - Creating a Custom Stack Topology: airstack stack new -> entry-file wiring (single-locus) -> modules.repos pins -> wiring regen -> doctor/wiring-mark validation; splits deferred to lite_offload_global - Adding a Vehicle Type, Unit, or Platform: vehicle.yaml (quad_default example, honest sim pass-through note), calibration overlay units, compute-platform compose/build chain (l4t precedent, CI-untested) - Getting the Most out of Your Coding Agent: design-spec-first notebook workflow, skill-directed prompting, lettered results artifacts, capture-discovered-knowledge loop Nav: new How-to -> Autonomy group (also absorbs Integration Checklist and Coordination Payloads); Create a Custom Stack under Modules & Stacks; vehicle guide under Robot & Field; coding-agent guide under Contributing. Concepts tab moved directly after Tutorials (conceptual grounding before task recipes). UE->Isaac export tutorial refreshed: new walkthrough video (cMjO7Sb7Zmo), instruction to export Z-up with scale in meters (unlike the video), and a warning that UE Decals (paint markings, dirt, puddles) do not export — bake them into textures instead. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… guide New tutorials completing the Tutorials tab learning path (Get AirStack Flying -> GCS mission -> parameter loop -> modular walkthrough -> first module -> first fleet -> own scene -> hardware), each a single golden path with per-step checks, every command verified (several executed): - Fly a Mission from the GCS: takeoff, waypoints, geofence, Navigate, land, save (panel names/defaults verified against the extension bundle; honest no-obstacles note for the default scene) - Change a Parameter: takeoff_velocity edit -> relaunch -> observe; verified that config YAML is symlink-installed from the bind-mounted source so NO rebuild is needed, and the code path that makes the panel's velocity=0 fall back to the config value - Write Your First Module: ran the actual scaffold for ground truth; handles the scaffold stub's double-namespace gotcha (robot.launch.xml already pushes the ROBOT_NAME namespace) - Your First Fleet: two-robot fleet YAML validated with resolve_fleet.py; documents the real per-robot tab / Robot-field targeting mechanics from render_layout.py - Build and Fly Your Own Scene: no-UE golden path (GUI stage -> scenes.yaml entry -> --scene flight -> baked contained scene.usd); the catalog-resolution check was actually executed How-to guides: - NEW Adding a Controller: verified chain trajectory_controller tracking_point -> pid_controller -> interface/cmd_roll_pitch_ yawrate_thrust; Path A (swap the feedback controller) vs Path B (take over the full spec-§5 surface, obligations enumerated); flight-test marks chosen for what each actually exercises - Adding a Planner renamed/expanded to Adding a World Model and Planner: local world-model+planner matched pairs (disparity pipeline worked example; full_droan_cpu swaps the pair together) vs the spec'd §3 global map interchange; new Path C Nav: Tutorials tab reordered to the learning path; Autonomy group gains Add a Controller and the renamed guide. What-Next hub lists the sequence. Release notes updated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Human-facing tutorials now teach the human workflow: hop into the container with 'airstack connect robot-desktop' (attaches to the container's tmux session; new shell window with Ctrl-b c, detach with Ctrl-b d) and run bws/sws/ros2 commands interactively, instead of docker exec bash -c one-liners. Applies to first_module.md and change_a_parameter.md (5 spots). Host-side 'docker logs' checks stay, noted as the tmux-mirror view. The non-interactive docker exec pattern remains, deliberately, in the agent-facing docs (working_with_coding_agents.md, AGENTS.md). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
andrewjong
added a commit
that referenced
this pull request
Aug 28, 2026
…y impact airstack-paper now sits on develop @ d4a04df (modular restructure + Diátaxis docs overhaul, PR #404 — closing the merge-not-recorded gap in §Campaigns). Direction log notes the lead's flag: the restructure will impact the agent study and may impact its numbers — pins and judge budgets predate it, so a re-pin means a new campaign id. Commit hashes cited in the log re-mapped to their rebased values. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
The docs site grew through the monolith→modular transition without an explicit information-architecture model. A full audit of all ~110 documents against the Diátaxis framework (classification of every page, mechanical verification against
airstack.sh/.env/compose/pytest.ini/message packages) found five clusters of problems:interface/cmd_vel, phantom--recreateflag, three-way requirements contradiction).{==TODO==}markers..envschema; noairstack_msgsdocs (the doc standards themselves cited a message type that doesn't exist).What changed (12 commits, intended for squash merge)
6d0bf18dtask_msgsactions)31f2ffc2frame_conventions.mdrewritten from live code (themap_FLUstory matched nothing in the repo); git-hooks READMEs → deprecation notices20a6b1f6vehicle.yaml/module.yamlschemas, calibration contract, RViz panel manuals, LiDAR filter README, OSMO lab-admin guide6197dd8cd2dbe79centrypoint.sh)25ccbd84system_architecture(643→375 lines, invented perf tables gone), CI/CD → + Using CI how-to, Foxglove → + Extending the Visualizer, Isaac docker → + Container Workflows1b988c99odometry_conversion), robot configuration, HITL (now uses thegcs-realhitlprofile + Foxglove verification), data-offloading fork resolved; 6 layer-index stubs filled4c3ccf3d.envschema,airstack_msgsreference, trajectory-library YAML format, platform matrix, Deploy to Hardware tutorial, Operating the GCS65e3930d0.20.0-alpha.15+ release-notes entryc98a3d1emodule create --in-treescaffolding choice; Concepts tab moved after Tutorials; UE-export tutorial refreshed (new video, Z-up/meters, Decals warning)d73d44e7trajectory_controller → pid_controller → interfacechain)ba943255airstack connectinstead ofdocker execone-liners (agent docs keep the non-interactive idiom deliberately)Validation
mkdocs build --strictpasses after every commit and at HEAD;mkdocs-redirectsentries cover all removed URLs.VERSIONbumped0.20.0-alpha.14 → 0.20.0-alpha.15(regex-validated againstcheck-version-increment), release notes updated under0.20.0 (Unreleased).resolve_fleet.py, the scene-catalog resolution check run for real.Maintainer decisions made (please sanity-check)
task_msgsactions, with honest implementation status (spec §8 and tasks.md now agree).Follow-ups (out of scope, flagged)
airstack config git-hooks(config.sh:86-122) still installs the docker-versioning hook that the semver gate rejects — small CLI removal PR recommended (READMEs now warn).tools/gen_docs_catalog.pytemplate polish (dedupe the per-page compat explainer; contextualize registry notes).PlanToWaypoint.srvmissing fromrosidl_generate_interfaces(never built);pid_controllerhas no README; the Foxglove robot-commands panel lacks the RViz panel's airborne gating (documented accurately).🤖 Generated with Claude Code