Open source CapCut alternative.
TypeScript
docs: add the writing style guide every piece of writing follows
David Le80c544753b6f
diff --git a/docs/README.md b/docs/README.mdindex cabcd82c..a5bddb01 100644--- a/docs/README.md+++ b/docs/README.md@@ -35,10 +35,10 @@ Supported product and engineering guides live in `docs/guides/`. This list is th- [Swift Guide](guides/swift.md) — the MVC split, language defaults, concurrency, SwiftUI, Mac platform behavior, data, and tests for the iOS and Mac apps.- [Code Review Guide](guides/code-review.md) — what makes a change reviewable, and how we review.-- [Writing Style](guides/writing-style.md) — the one voice for everything we write: docs, articles, marketing, UI copy, commits, and chat.+- [Writing Style](guides/writing-style.md) — the style every piece of writing follows: documentation, marketing, and everything else.- [Engineering Doc Style Guide](guides/eng-doc-style.md) — the required structure, sentence-level rules, and post-writing test for every doc here.-Add or update an entry here when behavior becomes supported. Don't duplicate this index in subdirectories or app folders; link directly between related docs only when the relationship helps a maintainer. Write in the voice of the [Writing Style](guides/writing-style.md) guide, and structure docs following the [Engineering Doc Style Guide](guides/eng-doc-style.md).+Add or update an entry here when behavior becomes supported. Don't duplicate this index in subdirectories or app folders; link directly between related docs only when the relationship helps a maintainer. Follow the [Writing Style](guides/writing-style.md) guide, and structure docs following the [Engineering Doc Style Guide](guides/eng-doc-style.md).## Navigation Rulesdiff --git a/docs/guides/eng-doc-style.md b/docs/guides/eng-doc-style.mdindex 91398d39..595036eb 100644--- a/docs/guides/eng-doc-style.md+++ b/docs/guides/eng-doc-style.md@@ -3,8 +3,8 @@How to write the docs in this repo: architecture notes, runtime specs,contributor guides — anything a teammate or a coding agent reads once and thenhas to follow. Lead with the point, keep it short, and write like a person.-The voice is the one in the [Writing Style](writing-style.md) guide; this doc-adds the structure an engineering doc needs on top of it.+Every doc follows the [Writing Style](writing-style.md) guide; this doc adds+the structure an engineering doc needs on top of it.## Principlesdiff --git a/docs/guides/writing-style.md b/docs/guides/writing-style.mdindex eed5efcf..acc23f94 100644--- a/docs/guides/writing-style.md+++ b/docs/guides/writing-style.md@@ -1,117 +1,30 @@-# Writing Style+Write a technical article in the style of a thoughtful engineer sharing something they learned while building real software.-How everything from Donkey reads: docs, guides, blog posts and articles, landing-page and marketing copy, release notes, emails, UI copy, commit messages, and-what the assistant says in chat. One voice everywhere.+The writing should be:-**The one rule:** write like a thoughtful engineer explaining something they-learned while building real software, to a peer, out loud. Calm, curious,-precise, and simple without being dumbed down.+* Conversational, calm, and technically precise+* Simple without being dumbed down+* Curious and analytical rather than authoritative+* Focused on explaining *why* something works, not just *what* to do+* Concrete, with real examples and small pieces of code where useful-## The Voice+Start with a real problem or observation. Build a mental model from first principles, then use that model to explain the solution and its tradeoffs.-The reader is a smart person who was not in the room. The writing brings them-into the room. It walks them from the problem to the model to the answer, so-that by the end they understand *why* the system behaves the way it does, and-could rederive the answer themselves.+Avoid:-That shape holds whether the piece is a two-thousand-word article or a-one-line tooltip. The article walks the whole path. The tooltip says the one-true thing the path ends at.+* Marketing language+* Generic introductions+* “In this article, we will...”+* Excessive headings and bullet points+* Unnecessary jargon+* Repetitive summaries+* AI-sounding phrases+* Overly polished or corporate writing-- **Conversational and calm.** Plain words, first person where it fits, no- drama. The tone of someone who has already solved it and is now thinking it- through for you.-- **Technically precise.** Every claim is one you could check. Name the actual- mechanism. If the number matters, give the number.-- **Curious over authoritative.** "Here is what I noticed, here is why I think- it happens, here is what that implies." Reasoning in the open. The reader- gets to disagree with a step.-- **Why before what.** A rule without its reason gets misapplied the first time- the situation shifts. Explain the reason and the rule follows.-- **Concrete.** A real problem, a real example, a small piece of code where it- helps. One specific case beats three general statements.+Make it feel like an experienced engineer thinking through a problem in public. The reader should finish understanding *why the system behaves the way it does*, not just memorizing a solution.-## The Shape of a Piece+Topic:+[TOPIC]-Start with a real problem or observation. Something that happened, something-that was surprising, a question a colleague asked. The first sentence already-has content in it.--Build a mental model from first principles. What are the parts, what does each-one know, what constraint is each one under. Keep it small. A model with three-moving pieces that the reader can hold in their head beats a complete one they-cannot.--Use the model to explain the solution. The fix should feel inevitable once the-model is in place. If it does not, the model is missing a piece.--Say what the tradeoffs are. What the solution gives up, when it stops being the-right call, what you would watch for. This is where the reader learns to trust-you.--Stop when the content stops. No wrap-up paragraph, no restated conclusion, no-offer of more.--```text-observation → model → solution → tradeoffs → stop-```--## Sentences--- Short sentences carry rules. Longer ones carry the why. A sentence past- twenty words is usually two.-- Active voice with a named actor. "The engine watches the parent process"- beats "the parent process is watched."-- State what a thing is, then stop. Never frame it against what it is not. Cut- every "X, not Y", "X rather than Y", "X instead of Z". If the reader would- not have assumed Y, naming Y teaches them a wrong idea on the way to the- right one.-- Say it straight, with the strong verb. "Adapters never hold task state"- beats "adapters should generally avoid holding task state."-- Prose is the default. Headings and bullets appear when the content really is- a list or really does change subject. A run of three bullets that could be- one paragraph is one paragraph.-- Code font only for what someone will type or read in a file. Describe tools,- types, and paths in words.--## Cut--- Marketing language. "Powerful", "seamless", "blazing fast", "effortless",- "delightful". If the thing is fast, say how fast and why.-- Generic openings. "In this article we will", "in today's world", "have you- ever wondered". The first sentence has content in it.-- Announcements of what the writing is about to do. "Let's dive in", "let's- break this down", "now let's look at".-- Filler that signals insight. "Worth noting", "it's important to understand",- "the key takeaway is", "at the end of the day". If it matters, say it. If it- does not, cut it.-- Repetitive summaries. A closing paragraph that restates the piece. A- "conclusion" heading. A "TL;DR" for something the intro already led with.-- Jargon that plain words cover. Coined names, internal acronyms, and file- paths go stale and read as noise.-- Hedges on things you know. "Might", "could potentially", "in some cases" when- it is simply true.-- Corporate polish. Every sentence the same length, every paragraph three- sentences, every idea in a bullet. Let it breathe unevenly, like a person.-- Rhetorical questions the next sentence answers. Ask the question because you- do not know, or state the answer.--## Where It Applies--| Surface | What it looks like |-| --- | --- |-| Articles and blog posts | The full path: observation, model, solution, tradeoffs. Small code where it helps. |-| Engineering docs and guides | Same voice, with the structure in the [Engineering Doc Style Guide](eng-doc-style.md): lead with the point, name the invariants, facts in tables. |-| Landing page and marketing | The problem in the reader's words, then what Donkey does about it, in the same calm voice. No superlatives. The proof is the specific. |-| Release notes and emails | What changed and why someone would care, in one or two plain sentences each. |-| UI copy and tooltips | The one true thing, in the fewest plain words. |-| Commit messages and code comments | What the change does and why, as a peer would explain it in review. |-| The assistant in chat | Recommendation first, then the why. Same calm, same precision. |--## Before You Ship It--1. Does the first sentence have something in it?-2. Could the reader explain *why* it works, without you there?-3. Is there a sentence a marketing team would have written? Cut it.-4. Does it stop when the content stops?+Notes:+[NOTES]