Design for developers. The API is the product.

Product discovery

Developer interviews. Working with product and architecture, we ran discovery sessions with a body of customer developers — the people integrating against the platform today — on what made an API trustworthy in practice. The pattern was consistent: they judged an API by its consistency before its features, they read the reference before the code, and one wrong example in the docs cost more trust than a missing operation. That set the bar: the documentation had to be generated from the code and tested against it.

Task analysis. We mapped the operator's actual jobs — test a vehicle, onboard a fleet, create a group, push an update, see how the fleet is doing, chase a quiet vehicle — and found that no listing of commands answered the question they arrived with, which was "where do I start." The menu now opens on those tasks, in order, with the reason each step is a step.

Validation against the build. Developers worked with the CLI and portal as they shipped. The findings were specific and unglamorous: a manifest named Fleet Onboarding – Wave 2 (final).csv could not be typed at a shell without getting escaping right, so the tool accepts a file dragged from Finder and cleans every way a terminal mangles the path. Four examples in the command reference and five in the API reference turned out to be wrong the first time a test tried to run them — the kind of error no reviewer had caught and every developer would have.

Key solutions

The command grammar. auto <noun> <verb> [scope] [output]. Ten nouns, each with its own page. Verbs in three layers: list and show on every noun; validate | plan | apply | watch borrowed from terraform and kubectl so that "apply a manifest" arrives with its meaning already learned; and only then the verbs that belong to one noun. A single selector grammar — --vehicles, --group, --match, and their excludes — with identical semantics on every command, resolved by one implementation. The rules are assertions in a test, not conventions in a style guide, because a rule enforced by review lasts until the reviewer is busy.

[Diagram 1: the command grammar]

One source, every surface. The noun table and the API reference live beside the code. The menu, the help pages, auto docs, the OpenAPI spec and the portal's reference all render that one table, and a test walks every example each of them offers and dispatches it. Add, rename or drop a field and the documentation fails until it matches. The portal never authors a sentence about the contract; it renders what the CLI emits.

[Diagram 2: one source, many surfaces]

Honesty in the instrument. Link state is a glyph and a word, never colour alone. A frame that was buffered on the vehicle during an outage arrives tagged, keeps the time it was measured, and never refreshes liveness or inflates the arrival rate — it says nothing about now. A geofence crossing is shown as a window, not an instant, because position is sampled. At fleet scale, silence is decomposed into never-provisioned, parked, and stopped unexpectedly, and only the last one is a fault; a dashboard that totals them makes a depot of parked vehicles look like a depot that has fallen over.

The portal proves it rather than claiming it. A single self-contained HTML file, zero external requests, runs from a USB stick. It replays real traces the CLI produced through twenty-one conformance checks, plots the vehicle on real street geometry, models the fleet at 48,000 vehicles, and then runs an actual end-user application — a web dashboard and a phone app — on the same event stream. When the link drops, you watch what each surface admits to. That tab answers "can I build my product on this" by showing the product.

[Image: device preview tab during an outage]

The reference says what isn't built. Twenty-seven of the sixty-four documented operations are designed and not yet implemented. Rather than let a reader infer that from an absence, every operation carries its status — implemented, simulated, or designed — on the page and in the OpenAPI spec, and the spec leads with an empty servers block and a note saying why, because a generator will point a client at whatever base URL it finds.