Docs Writer

Documentation Writer

Draft or rewrite Strands Agents documentation following the five-layer voice stack.

Inputs

• Content type: tutorial, howto, reference, explanation, blog (required)
• Topic: What this page covers (required)
• Target file: Path in docs repo where this will live (if known)
• Existing content: Current page to rewrite (if rewriting)
• Context (optional): Community signals, GitHub issues, or positioning themes motivating this work

Process

Step 1: Load voice context

Read these files before writing anything:

1. ../../references/voice-guide.md (the full voice stack)
2. ../../references/terminology.md (canonical terms)

If rewriting, read the current published page as a baseline.

Step 2: Outline

Produce an outline where each item is the question that section answers.

• Tutorial: step-by-step journey toward a working result
• How-to: prerequisites, steps, expected result
• Reference: API surface (classes, methods, parameters)
• Explanation: problem, design choice, tradeoffs, implications

Each section answers one question. No mixed-type sections. Review for scope creep.

Step 3: Draft

Write each section following the outline.

• First sentence of every section describes the developer's goal (framing layer)
• Use the tone appropriate for this content type (register layer)
• Code examples: runnable with real Strands imports and realistic values
• For agent responses, label non-deterministic output following the patterns in voice-guide.md under "Documenting non-deterministic behavior" (typical output as a comment under the code; capability language for tool selection).
• Comments explain intent, not mechanics
• One concept per code block
• Match snippet length to the complexity of what's being demonstrated. Bias toward brevity. If setup machinery dwarfs the feature being shown, the snippet is overweight.
• Snippets must be copy-paste-runnable: imports present, variables defined, no missing context.
• Prefer prose over a snippet for trivial API surface. A single property, a single method call, or a one-line config change is often clearer as inline backtick code in a sentence than as a dedicated code block. Reach for a snippet when the shape, ordering, or interaction between calls carries the lesson.
• Diagrams use ```mermaid fences (flowchart, sequence, etc.). Never use ASCII art or box-drawing characters for diagrams. The site renders mermaid natively.

Step 3b: Apply MDX formatting

Apply MDX formatting patterns from ../../references/mdx-authoring.md — especially Tabs/Tab syntax, the <Syntax> component for inline language-specific identifiers, snippet includes, and callout syntax (default to inline prose; callouts are rare).

When shared prose needs to reference a language-specific identifier (method name, parameter, class, etc.), use <Syntax py="..." ts="..." />. This keeps prose clean and adapts to the reader's language selection. Never spell out both variants manually in prose.

TypeScript code is never inlined in MDX. All TypeScript examples live in runnable .ts snippet files alongside the page and are included via --8<-- directives. Two files per page:

• <page>_imports.ts — one named snippet region per example's import set. Every example gets its own imports snippet so the rendered block is self-contained.
• <page>.ts — body snippets scoped in blocks.

In the MDX, each TypeScript code fence contains two --8<-- includes (imports + body) inside a single fence so it renders as one copy-pasteable block. Every example must include its imports — a body-only include that omits the import line produces a snippet that isn't runnable.

Read ../../references/mdx-authoring.md ("Snippet Inclusion" and "TypeScript Snippet Scoping") for the full specification. Look at any existing page with TypeScript tabs in the same directory for the concrete file layout.

Python code may be inlined directly in the MDX since Python files in the docs tree don't go through a type-checker.