writing

name

writing

description

Write or revise Learn articles under web/learn/, READMEs, changelogs, and release notes. Owns Learn-site article structure, interlinking, and the doc revision pass for those surfaces. For technical product docs under web/docs/** (and roadmap/security feature-status copy), use the docs-writing skill instead. Voice, Orwell's rules, ASD-STE100, buzzword banlists, and AI-tell checks live in the explain-to-me skill: read that first whenever you draft or edit prose.

Writing in the treq voice

When to use

• Drafting or revising Learn articles under web/learn/**.
• Revising existing Learn prose to match the house voice.
• Running a de-slop edit pass on AI-generated Learn text before it ships.
• READMEs, changelogs, and release notes that are not product how-tos.

Technical product docs (web/docs/**, roadmap feature status, security claims about product integrations) use /docs-writing. That skill owns shipped-vs-WIP accuracy, prerequisites, and cross-page consistency. Come back here for Learn-site structure and interlinking.

Voice and banlists live in explain-to-me. Read .claude/skills/explain-to-me/SKILL.md before you draft or revise. It owns:

• The house voice model
• Orwell's six rules and ASD-STE100
• Where software terms fit
• Voice rules, formatting hard bans
• Buzzword / marketing banlist and AI-tell banlist
• Annotated exemplars
• The readability checker script

This skill extends that foundation with site-doc structure and interlinking. Where web/STYLE_GUIDE.md and explain-to-me agree on formatting, the style guide wins. Where you need what the voice sounds like, use explain-to-me.

Structure for concept and workflow articles

Follow the skeleton the existing docs use.

---
sidebar_position: N
---

import DefinitionCard from '...'

# What is X?

_One-line italicized description, direct and precise._

Opening paragraph, 2 to 3 sentences. No lists here.

## Introduction
## Understanding the Concept
## Applying It in Practice
## Engineering Considerations
## Scaling & Operational Considerations
## Next Steps

• H2 only. Keep the structure flat, no H3 or H4.
• Introduce each key term with a <DefinitionCard term=... definition=... /> and bold the term on first mention in prose.
• Use <ThemeAwareImage src=... alt=... /> for diagrams.
• Use tables for side-by-side comparisons and dense reference data.
• Mark version-specific features with the admonition: :::tip Added in v1.8.0 ... :::.
• ## Next Steps is a short list of links to sibling docs.

Prose inside every section must follow explain-to-me.

Interlinking across the content site

Treat every article as a node in the site, not a standalone page. Readers land on one doc from search and decide whether to keep reading the site from whether it points them somewhere else useful. Search engines read the same signal: an article whose key terms link to the other articles that cover them is what makes the site's internal link graph work for SEO. An article with no outbound links and no inbound links is dead weight in that graph, regardless of how good the prose is.

Where links go

Inline, in prose, at first meaningful mention. When you name a concept, tool, or workflow that has its own article elsewhere on the site, link it the first time it appears in the body, not every time it recurs.

Use separate clones when tasks need independent refs, remotes, or repository configuration.

This is a real sentence doing real work. The link is not bolted on. Do not add a second link to the same target later in the same doc, and do not interrupt a sentence's flow just to fit a link in: if no natural mention exists, wait for the ## Next Steps list instead of forcing one.

## Next Steps (or ## Related) at the end. A short list, 3 to 5 items, each a link plus a one-clause description of what the reader gets:

## Next Steps

- [What are Stacked PRs?](./stacked-prs): manage branches that depend on one another
- [Stacked PR Workflow](/learn/workflows/git/stacked-pr): apply rebasing to a pull-request stack

This section is a map, not a repeat of the body. Do not just relist links already made in prose, add the adjacent articles a reader would want next.

Link syntax

• Same directory or a near sibling: relative, no extension: [text](./git-worktrees-vs-clones).
• Anywhere else on the site: absolute from the content root, no extension: [text](/learn/concepts/git/git-worktrees), [text](/docs/concepts/workspaces).
• Never link a bare URL or write "click here". The anchor text is the term or phrase itself, exactly as it reads in the sentence.
• Verify the target actually exists (check the file under web/learn/ or web/docs/, or run the audit-interlinking skill's checker) before writing the path. A guessed path that is close but wrong is a broken link.

What earns a link

Link a term the first time you use it if, and only if, another article on the site is the definitive treatment of that term. Do not link:

• A word that merely resembles another doc's title in a different sense.
• Your own doc's own subject (do not link a concept article to itself).
• A tangential mention that is not what the sentence is actually about.

Every new or revised article should end up with at least 2 to 3 in-body links to genuinely relevant existing articles, plus a ## Next Steps list. If you cannot find that many relevant targets honestly, write fewer rather than padding with weak matches. A forced link reads exactly like the AI tells explain-to-me already bans: decoration instead of information.

Auditing across the whole site

For a bulk check across many articles (broken links, orphaned pages, articles that are under-linked, or finding where an article's key terms should link out) use the audit-interlinking skill. It runs a link-graph checker and turns the results into a worklist you still verify by reading, since keyword matches are candidates, not verdicts.

Revision and de-slop pass

Run this against any draft before you return it.

1. Apply the explain-to-me quick check (Orwell, ASD-STE100, hard bans, buzzwords, AI tells). Run the checker script: python3 .claude/skills/explain-to-me/scripts/readability.py path/to/doc.mdx Fix every hard ban, buzzword, and AI tell it reports, and pull long sentences apart.
2. Check paragraph length. Anything over 4 sentences gets split.
3. Check every claim is declarative, not hedged.
4. Remove any sentence that restates a point already made.
5. Verify against the three criteria from web/learn/workflows/ai/ai-documentation-writing.md: technical accuracy (every claim checks out against the source), reader appropriateness (the intended reader understands it at first read), and task completeness (a reader can act on it using only this text).
6. Check interlinking: at least 2 to 3 in-body links to genuinely relevant existing articles, a ## Next Steps list, and every link target verified to exist. See the Interlinking section above.