Skip to content
design
Foundations

Content

How bosun writes to the crew, to engineers and to customers.

On this page
Couldn't save the waypoint1 because the GPS lost its fix.2 The route is kept on this device.3 Save again once the fix returns.4
1 What happened2 Why3 What survived4 What to do
One message, four parts: what happened, why, what survived, and what to do.

The reader of a crew-facing message is on a vessel at sea, often tired, often in the middle of a task, and may hear the message through a speaker. The rules on this page cover every string a mariner sees or hears: voice output, UI text, alert text, onboarding and tool results. The repository's writing-crew-facing-messages skill holds the full rules; this page shows them.

01Say what happenedAn active sentence in the crew’s terms: "Couldn’t save the waypoint." Not "Save failed", not "Error 42", not a stack trace.
02Say what survivedTell the crew what was not lost, so they do not redo work that is already safe.
03Say what to doName the next step. If there is nothing to do aboard, give the way out: retry, restart or fall back to manual.

In this section

Voice and toneHow the site and the product pages speak to sailors.Inclusive writingWords that work for everyone aboard, in every language, on screen and out loud.Date and timeThe 24-hour clock, dates by locale, durations and ages.Error messagesWhat happened, why, what survived, and what to do.Attention messagesBefore something goes wrong: the consequence and the safe choice.Info messagesUseful facts, without interrupting.Success messagesConfirm the outcome and how to undo it.Empty stateNothing to show: why, and whether the source is working.Feature discoverySomething new, at a quiet moment.

Messages

Do
Couldn't save the waypoint because the GPS lost its fix. The route is kept on this device. Save again once the fix returns.
Name the problem, the cause, what is safe and the next step.
Don't
Error 42: save failed.
Don't hand the crew a code. It says something broke and nothing about what to do.
Do
We're having trouble reaching the chart server. Charts already on this device still work. We'll keep trying in the background.
Own the problem, plainly, and say what still works.
Don't
Oops! The chart provider's API is down.
Don't joke, and don't blame a supplier. The crew needs the state of the vessel, not the state of a vendor.

Voice

A spoken summary is one sentence. The most important fact comes first, numbers are included, and there is no list. It carries the same four parts, compressed.

Voice"The anchor is dragging, 38 meters outside the swing circle; check the chart and get ready to re-anchor."
Spoken summary

Values and units

Do

8.4m

Set the unit small and dim, right beside the value.
Don't
Depth: 8.4 meters
Don't spell the unit out at the size of the value, or label it twice.
Do

14kn , gusts 22 kn

TWD 214°
Write wind as its speed and its gusts, each with its unit, and the direction it comes from beside it.
Don't
☁️ Windy, 14 to 22 knots
Don't use weather pictures or a range in words. A cloud says nothing about the gusts.
Do

▲ +0.3 m / 10 min

Quantify a trend: the direction, the amount and the period.
Don't
↑
Don't show a bare arrow. Rising by how much, and over what time?

Writing for engineers and customers

Reports, docs and CLAUDE.md files follow the repository's Prose rules: say what you mean, and use a literal phrase wherever one exists. A sentence names the mechanism and its consequence, so a reader can check it against the code. The site and the product pages speak to sailors deciding, in the words of the sea and with professional confidence; Voice and tone holds that voice.

Evidence and document context

A report opens with its title, description, audience, date, category and publication/distribution state. Name the question it answers before presenting the implementation. Separate observed results, interpretation, proposed work and unknown facts. A decorative accent never establishes approval or confidentiality.

Choose blocks by the information: facts for named attributes, metrics for measured quantities, a process for ordered steps, a decision for alternatives and rationale, and a figure for visual evidence. Keep the useful meaning in search and Markdown exports as well as the page. See Report types for audience-specific structures and Report metadata for the header.