diff --git a/WRITING_PROFILE.md b/WRITING_PROFILE.md new file mode 100644 index 0000000..ab91390 --- /dev/null +++ b/WRITING_PROFILE.md @@ -0,0 +1,231 @@ +# LOOKOUT Writing Profile + +A working voice guide for all LOOKOUT communications — release notes, product +copy, blog posts, emails, social, support replies. It synthesizes three +sources: + +- David Rose's best writing in *Enchanted Objects* (2014) and *SuperSight* + (2021). +- Steven Johnson's narrative non-fiction, especially *How We Got to Now*. +- The LOOKOUT brand voice — a maritime augmented-reality product that gives + boaters new senses. + +The goal is communication that feels written by a person who reads widely, +builds carefully, and loves boats. Never copy that sounds machine-generated +or corporate. + +--- + +## 1. The three voices, in one paragraph each + +### David Rose (Enchanted Objects, SuperSight) +Rose writes about technology the way a naturalist writes about birds — +with curiosity, taxonomy, and a refusal to be jaded. He favors concrete +nouns over abstractions ("a wand," "a mirror," "a pill bottle that +glows"), reaches for mythology and folk objects to explain new machines, +and treats every gadget as a small character with motives and manners. +His sentences are clean and unshowy, but they reward re-reading: a +metaphor is doing structural work, not decoration. He is optimistic +without being naive, and he is never embarrassed by wonder. + +### Steven Johnson (How We Got to Now) +Johnson's signature is the *long zoom*: he starts with a detail — a +shard of glass, a block of ice, the smell of a London sewer — and pulls +back until the reader sees a centuries-long chain of consequence. He +loves the *hummingbird effect*, where an invention in one field +unlocks something nobody predicted in another. His tone is +conversational but rigorous; he never talks down, but he also never +forgets that he is telling a story. He names the inventors history +forgot, and he lets a counterintuitive fact land before he explains it. + +### LOOKOUT brand voice +LOOKOUT augments the senses of people on boats. The product gives a +helmsman the perception of a thousand-year-old lighthouse keeper and a +satellite, at the same time. The voice that fits the product is +therefore: alert, observant, plainspoken, occasionally lyrical about +the sea, and quietly competent. Boaters distrust hype; they trust +people who have been wet and cold. Write like one of them. + +--- + +## 2. What the synthesis looks like + +When the three are blended, the resulting voice has six habits. + +**1. Concrete before abstract.** Lead with the thing you can see, hear, +or feel. "The wake animates" before "improved visualization." A horizon +*line* before a horizon *feature*. + +**2. The long zoom, in miniature.** Even a one-line release note can +gesture at why it matters. A faster frame rate isn't a number; it's the +difference between glancing at a screen and trusting it. + +**3. Metaphor that earns its keep.** A good metaphor compresses an +explanation. A bad one is decoration. Reach for the sea, the sky, the +old crafts of navigation (charts, sextants, lighthouses, dead +reckoning, the lookout in the crow's nest) before reaching for +software metaphors. Use one strong image, not three weak ones. + +**4. Wonder without hype.** "Magical" is a word to *earn*, not to +*claim*. Describe what the system does so precisely that the reader +arrives at wonder on their own. Never tell the reader something is +amazing. + +**5. Respect the reader.** Boaters are intelligent adults operating +expensive, dangerous machines in weather. Write to that person. Don't +explain what AIS is in a release note for someone who has been using +AIS for ten years. Don't dumb down; don't show off. + +**6. Short, then long, then short.** Vary sentence length on purpose. +A run of short sentences feels urgent. A long sentence with two commas +and a clause can do work the short ones can't. End paragraphs on a +short one when you want the reader to look up from the page. + +--- + +## 3. Vocabulary + +### Prefer +- **Verbs of perception:** see, watch, glance, scan, spot, notice, + glimpse, sweep, track, read, hear, feel. +- **Verbs of motion:** glide, lift, settle, drift, swing, hold, steady, + cut, carry, run. +- **Sea nouns:** chop, swell, wake, set, drift, fetch, lee, bearing, + heading, fix, mark, watch, stand, pass. +- **Craft nouns:** chart, lens, mirror, compass, sextant, lighthouse, + lookout, log, almanac. +- **Plain English:** use, help, show, find, fix, faster, clearer, + steadier, simpler. + +### Avoid +- **Empty superlatives:** amazing, incredible, revolutionary, + game-changing, world-class, best-in-class, next-generation. +- **Corporate filler:** leverage, robust, seamless, frictionless, + empower, unlock value, solutions, ecosystem (when used as + metaphor for a product line), synergy, holistic. +- **Tech-bro tics:** "we're excited to announce," "stay tuned," + "delight," "magical experience," "AI-powered" as an adjective, + "reimagined." +- **Weasel words:** various, several, certain, some, many (when a + number would do). +- **Vague verbs:** enable, facilitate, provide, deliver, drive + (as in "drive engagement"). + +### Punctuation and rhythm +- Em dashes are welcome and earn their keep. +- Semicolons over the comma splice; both over the run-on. +- One exclamation point per document, maximum. Usually zero. +- No emoji in product copy. (Emoji are fine in casual Slack.) +- Oxford comma, yes. +- Sentence-case headings, not Title Case Marketing Headlines. + +--- + +## 4. Patterns that work + +### The vignette opener (Johnson) +Open longer pieces with a moment — a specific boat, a specific +afternoon, a specific near-miss — and pull back to the point. The +reader will follow a story further than they will follow a thesis. + +### The taxonomy (Rose) +When introducing a new feature category, give it a name and a kind. In +*Enchanted Objects*, Rose categorizes by archetype (the wand, the +talisman, the charm). LOOKOUT features can be grouped by what *sense* +they extend: sight (horizon line, AR overlays), memory (track replay), +hearing (alerts), reach (remote camera). + +### The hummingbird (Johnson) +When a small improvement enables a larger one, say so. "Smoother +streaming" is fine. "Smoother streaming, which is what lets the new +horizon line stay locked to the sea even in a beam swell" is the +hummingbird — and it's better writing because it's truer. + +### The honest small thing (LOOKOUT) +Not every release is a story. Sometimes a bug is a bug. When the work +is small, say so plainly. Padding a bug-fix release with adjectives is +how trust erodes. "Reconnection bug fixes and startup hardening" is a +good sentence. Don't gild it. + +### Show the seam (Rose) +Rose often shows the join between old craft and new tech: a wooden +umbrella stand that knows the weather. Where LOOKOUT bridges old and +new — a chart and an AR overlay, a paper logbook and a track replay — +name the bridge. + +--- + +## 5. Calibration by surface + +Different surfaces need different dials. The voice is constant; the +volume changes. + +| Surface | Length | Voice notes | +|---|---|---| +| Patch release notes | 1–5 bullets | Plain, precise. No vignettes. A small phrase of *why* on at least one bullet if there's one to give. | +| Minor release notes | 4–8 bullets | One bullet may carry a hint of story or consequence. Keep the rest crisp. | +| Major release notes | Short opener + grouped bullets | Two or three sentences up top to frame the release. Group bullets by the sense they extend, or by the part of the experience they touch. | +| Blog post / essay | Long form | Vignette opener. Long zoom. Earn the wonder. Bring in history if it is genuinely relevant, not as decoration. | +| Support reply | A paragraph or two | Plain, warm, specific. Name the thing, name the fix, name the next step. No marketing voice. | +| Social / short post | One or two sentences | Concrete image. No hashtags as punctuation. | +| Email to customers | Three paragraphs at most | One reason for the email. One ask or update. One human sign-off. | + +--- + +## 6. Before / after + +These are rewrites of real LOOKOUT release-note lines to show the voice +in motion. The originals are not wrong — they are just under-written. + +**Before:** Improved cloud updating mechanism. +**After:** Updates now arrive quietly in the background, without +asking the helm for attention. + +**Before:** Faster frame rate and smoother stream. +**After:** A faster frame rate. The view now reads the way the water +moves — without the small hitch that used to pull the eye. + +**Before:** Horizon detection. +**After:** A horizon line, drawn where the sea actually meets the sky +— so the overlay holds steady when the boat doesn't. + +**Before:** Automatic horizon stabilization when IMU data is available, +including support for manual roll offset. +**After:** When the boat heels, the overlay no longer heels with it. +The IMU keeps the horizon level; a manual roll offset is there for +mounts that aren't. + +**Before:** Various smaller stability improvements and bug fixes. +**After:** A handful of small fixes and steadier behavior in edge +cases. (Use this line as is. Don't dress it up.) + +**Before:** New neural network with improved detection. +**After:** A new detection model. It sees smaller marks, sooner, and +mistakes fewer waves for boats. + +**Before:** Cleaner chart presentation with reduced vector symbols and +simplified styling. +**After:** The chart is quieter. Fewer symbols, simpler lines — so the +things that matter at a glance are the things that show up first. + +--- + +## 7. A short checklist before you publish + +Run any LOOKOUT-bylined piece through these eight questions. + +1. Is there a concrete image in the first sentence? +2. Have I used a verb of perception or motion where I could have used + "enable" or "provide"? +3. Did I claim "magical" or "amazing" — or did I describe something + precisely enough that the reader feels it? +4. Are there any words from the *Avoid* list in section 3? +5. Is there at least one sentence that varies the rhythm — a short one + among long ones, or a long one among short? +6. If a metaphor is doing work, is it from the sea, the sky, or the + old crafts of navigation? +7. Have I respected the reader as someone who knows boats? +8. Could I cut a third of the words without losing meaning? (Try it. + You usually can.) + +If a piece passes all eight, ship it.