Is your feature request related to a problem? Please describe.
The current documentation is deployment-focused. The README covers installation and operations thoroughly (Docker Compose, prebuilt release, build-from-source, environment variables, BlueSky ports, offline PMTiles basemap, and the integrated edition), and script/README.md documents the navdata build pipeline. But there is no end-user guide for actually running a simulation once WebATM is up.
A new user can get the web UI running at http://localhost:8082, but from there nothing explains how to connect to BlueSky, load/run a scenario, create and control aircraft, issue commands, or use the map tools. The feature list in the README names capabilities (command palette, console map picker, aircraft creation, routes/shapes, multi-node, 3D, follow mode) without showing how to use them. The result is a steep "now what?" cliff right after install.
Describe the solution you'd like
Add user-facing usage documentation — a Usage / User Guide with concrete use cases and step-by-step guides to run a simulation. This could be a new top-level section in the README and/or a docs/ directory linked from it (and screenshots/GIFs where they help).
Proposed step-by-step guides:
- Your first simulation in 5 minutes — from a fresh start to a moving aircraft on the map (connect → load a demo scenario or create one aircraft → run → observe).
- Connecting to a BlueSky server — standalone: Settings → server IP → Connect (note ports 11000/11001 and
BLUESKY_SERVER_HOST); integrated: the in-app Start button.
- Running a scenario (
.scn) file — upload/organize files via the in-app file manager and run them (incl. the IC command flow).
- Creating & controlling aircraft from the UI — the Create Aircraft modal + click-to-place on the map; single-click to fly-to, double-click to follow; reading the aircraft info panel; issuing commands (e.g.
HDG/ALT/SPD) from the console with tab-completion and the command palette.
- Using the map tools — drawing routes and shapes, and picking coordinates with the console map picker.
- Multi-node simulations — spawning and switching between parallel nodes.
- Customizing the display — labels, icons, trails, colors/styles, 2D ↔ 3D models, and Web Mercator ↔ globe projection.
- Integrated edition: managing the bundled server — Start / Stop / Restart / Kill and the live server-log tab.
Proposed use cases (the "why" framing each guide):
- A quick classroom/demo of an ATM scenario for teaching or evaluation.
- Validating a hand-authored or generated
.scn scenario file end-to-end.
- Running an offline/air-gapped demo using the local PMTiles basemap + navdata overlay.
- Driving a single-container deployment via the integrated edition's in-app server controls.
Describe alternatives you've considered
- Keeping everything in the README vs. splitting usage into a
docs/ folder linked from the README (likely cleaner as the guides grow).
- Text-only vs. adding short screenshots/GIFs (a few visuals would help a lot for the map-interaction guides).
- Relying on the live demo and BlueSky's upstream command reference instead of writing our own — but neither walks a user through the WebATM UI specifically.
Additional context
- Existing docs for reference:
README.md (install/deploy/config) and script/README.md (navdata pipeline).
- BlueSky stack commands referenced in the guides can link to the upstream BlueSky / amvlab/bluesky docs rather than being re-documented here.
- Guides should call out the standalone vs. integrated differences where the workflow diverges (e.g. connecting to a server vs. clicking Start).
Is your feature request related to a problem? Please describe.
The current documentation is deployment-focused. The README covers installation and operations thoroughly (Docker Compose, prebuilt release, build-from-source, environment variables, BlueSky ports, offline PMTiles basemap, and the integrated edition), and
script/README.mddocuments the navdata build pipeline. But there is no end-user guide for actually running a simulation once WebATM is up.A new user can get the web UI running at http://localhost:8082, but from there nothing explains how to connect to BlueSky, load/run a scenario, create and control aircraft, issue commands, or use the map tools. The feature list in the README names capabilities (command palette, console map picker, aircraft creation, routes/shapes, multi-node, 3D, follow mode) without showing how to use them. The result is a steep "now what?" cliff right after install.
Describe the solution you'd like
Add user-facing usage documentation — a Usage / User Guide with concrete use cases and step-by-step guides to run a simulation. This could be a new top-level section in the README and/or a
docs/directory linked from it (and screenshots/GIFs where they help).Proposed step-by-step guides:
BLUESKY_SERVER_HOST); integrated: the in-app Start button..scn) file — upload/organize files via the in-app file manager and run them (incl. theICcommand flow).HDG/ALT/SPD) from the console with tab-completion and the command palette.Proposed use cases (the "why" framing each guide):
.scnscenario file end-to-end.Describe alternatives you've considered
docs/folder linked from the README (likely cleaner as the guides grow).Additional context
README.md(install/deploy/config) andscript/README.md(navdata pipeline).