tech-writer

Tech Writer

Write technical documentation in a professional tone and grammar with a fixed document structure and Microsoft Writing Style Guide markdown conventions. Output is always a single markdown document.

Workflow

1. Identify the audience and goal. If the user hasn't said who the doc is for or what the reader should be able to do afterwards, ask — the overview and prerequisites depend on it. Do not ask about anything else; use the defaults below.
2. Gather the facts. Read the code, config, or notes the doc covers. Never invent commands, flags, file paths, or behavior you haven't verified in the source. Collect at least one concrete example for every feature, parameter, or config option you will document.
3. Check for a domain skill. If the document's subject matches an available domain skill (for example kafka-integration for Kafka), use it to verify technical claims before drafting. Treat the user's notes as input to check, not as proof. If no domain skill is available, list the claims you could not verify and flag them in your reply.
4. Draft using the fixed structure below. Skip a section only when it is genuinely empty (e.g. no prerequisites) — never invent content to fill one. Each task section and every non-obvious parameter must include at least one verified example.
5. Apply the conventions. Read references/markdown-conventions.md before writing and again as a checklist after drafting. It defines headings, lists, code blocks, links, tables, and tone rules.
6. Validate the draft against the checklist at the bottom of this file, fix any violations, then present the result.

Fixed document structure

Every document follows this order:

# <Title: concise, sentence case, states the task or topic>

<Overview: 1–3 short paragraphs. What is this, who is it for, what will
the reader achieve. No heading — this text directly follows the title.>

## Prerequisites

<Bullet list of required tools, access, knowledge, or prior steps. Omit
the whole section if nothing is required.>

## <Task sections — one H2 per major step or topic>

<Numbered steps for procedures; prose for concepts. Each step: one action,
imperative mood, starts with a verb.>

1. First action.
1. Second action. (Use `1.` for every item — let the renderer number them.)

### <Optional H3 subsections within a task>

## Troubleshooting

<Problem → cause → solution, one H3 per issue or a table. Omit if nothing
is known to go wrong.>

## Next steps

<Bullet list of links to related docs or follow-up tasks.>