Writing These Docs

---

This page is for anyone adding to these docs, human or agent. It records what the rest of the documentation already does, so that new pages read like they belong rather than like a different product.

When you are unsure about anything below, open Overview and Components & Connections and copy what they do. Those two pages are the reference for this style: short paragraphs that carry real information, tables where the content is genuinely tabular, one code block that earns its place, and a lot of air.

---

Voice

Write in plain, declarative prose. Address the reader as you and describe what the platform does in the present tense. Explain the reasoning behind a design, not just the steps, because a reader who understands why can adapt what they read; a reader who only has steps is stuck the moment their situation differs.

Prefer the specific to the general. Name the file, the field, the command. “Set health_check_path to a route that returns 200” beats “configure an appropriate health check.”

Some rules that hold everywhere:

• No em dashes. Use a comma, a period, or rewrite the sentence.
• No marketing adjectives and no hedging. If something is a tradeoff, say what the tradeoff is.
• Sentences stay under about 35 words. If one runs longer, it is usually two sentences.
• Every paragraph does one job. If a paragraph changes subject halfway through, split it.
• Say what a thing does before naming its options. Options mean nothing without the purpose.

---

Density and Typography

The most common failure in these docs is not wrong information, it is too much visual noise around correct information. Body prose runs at a generous line height with real space between paragraphs, and that rhythm is what makes a page feel approachable. Anything that interrupts it should earn the interruption.

Use inline code for literals only. Field names, values, file names, env vars, routes, and image references get backticks. Concepts do not. Write “the app container connects to the database” as prose, and save DB_HOST for the variable it actually names. A paragraph where every other noun is a grey chip is unreadable, and the chips stop meaning anything.

Use bold sparingly, for the lead-in of a list item or a genuine warning. Bold scattered through prose reads as shouting.

Keep code blocks under about 70 characters wide. The docs column is narrow; a longer line adds a horizontal scrollbar that never goes away. Break long JSON objects across lines rather than letting one line run.

Two spacing tiers. Paragraphs sit 20px apart. Figures, meaning tables and diagrams, sit 32px from whatever surrounds them, because a bordered block set at paragraph spacing reads as part of the paragraph above it. Code blocks keep the tighter 20px, since they almost always follow the sentence that introduces them. Spacing belongs to a figure’s wrapper, never to the table element itself, which would put the gap inside the border.

When you add a block element, measure the gap above and below it before calling it done. A wrapper with no margin of its own sits flush against the next paragraph, and one with margin on the inside pushes its own border away from its content. Both read as mistakes even when the block itself is right.

---

Page Shape

Most pages follow the same arc: a short intro that says what this is and who it is for, then sections in the order a reader needs them, then links onward. Reference pages lead with a table. Explanatory pages lead with prose.

Section headings (##) are Title Case, matching the sidebar. Keep the sidebar label, the page title, and any card that links to the page in agreement, so a reader scanning for one name finds it everywhere.

Subheadings (###) follow what they name. Title Case for a named thing, because that is its name: Docker Hub, File Upload. Sentence case for a description, because it is a phrase rather than a label: Build fails, Container won’t start. Pick one per page and hold it, so a reader can tell a list of options from a list of symptoms at a glance.

Separate major sections with a horizontal rule. It is the section rhythm the rest of the docs uses, and it gives long pages a scannable skeleton.

---

When to Use Each Component

A page that uses every component available is usually a page that has not decided what it is about.

---

Abstraction Level

Spawned’s premise is that infrastructure architecture is the layer you work in, and the implementation is generated beneath it, available at whatever granularity a requirement eventually demands. The documentation has to hold that line too.

Write about components and connections, and describe a connection by what it grants: a private path, an injected variable, a route in from the internet. Do not narrate the generated implementation, the security groups, target groups, task definitions, or resource identifiers, unless a reader genuinely cannot design correctly without it. Naming cloud plumbing teaches readers that they are responsible for it, which is the opposite of the product’s claim.

Keep pages agnostic about how the reader works, too. The canvas, the CLI, and a coding agent are three doors into the same model, so an explanation of an architecture should not assume any of them. Cover the three paths once, in one place, and let everything else describe the design.

---

Accuracy

Documentation that is wrong is worse than documentation that is missing, because a reader cannot tell the difference until it costs them an hour.

• Verify platform behaviour against spawned schema, which is the authoritative list of components, fields, and connections. Do not describe a field from memory.
• Verify third-party facts, such as an image name, port, or data directory, against that project’s own documentation.
• Any infra.json you publish must pass spawned validate exactly as written.
• Do not publish specific prices. Rates change and live on the pricing page.
• When docs change, update public/llms-full.txt in the same commit.

---

Adding a Page

Add the route under src/app/docs/, export a metadata object with a title and a description written for search results, and register the page in the sidebar in src/app/docs/layout.tsx. The search index regenerates automatically on the next dev or build.

Then read the page next to Components & Connections. If it feels denser or louder than that page, the problem is usually one of three things: too many inline code chips, a paragraph doing more than one job, or a component used where prose would do.