Technical Documentation Authoring
Compile technical documentation into a stable, maintainable, and easy-to-navigate knowledge carrier. First decide where facts belong and what the reader needs, then organize the content, and finally polish the expression.
Core principles
- Identify the type of information before writing; do not turn the discovery process directly into the article structure.
- Every persistent fact has exactly one canonical owner; the owner can be source code, configuration, schema, generator, documentation, or a decision record.
- Choose the document type based on reader intent, not based on the file name or existing materials.
- Establish a Document Contract before writing: reader, goal, subject, scope, exclusions, authoritative sources, and detail ceiling.
- Document types cannot expand the scope; parent documents summarize their direct children and link to the detail owner.
- Organize content by prerequisites, dependencies, and verifiable results, not by the order of investigation, implementation, or commits.
- Place the current state, design rationale, and historical narrative into different document responsibilities.
- When crossing boundaries, link to authoritative details; keep only content that is within the current scope and sufficiently stable.
- The primary agent freezes the authoring plan first, then decides whether to delegate; sub-agents only execute locally scoped writing tasks.
Working contract
Before performing writing, rewriting, splitting, merging, or structural review, form a short Document Contract. This can be done internally; only make it a visible artifact when the task requires alignment.
Record the following fields:
- Reader intent: The reader wants to learn, complete a task, query, understand, trace, or comply with rules.
- Document type: The primary document type that matches the intent; a document retains only one primary intent.
- Subject: The topic or system level that the document is directly responsible for.
- Scope: The objects, behaviors, and depth included.
- Exclusions: Content explicitly left for other documents or authoritative sources.
- Authorities: Source code, configuration, generated files, decision records, or existing documents that support the current facts.
- Detail ceiling: The highest level of detail allowed given the current subject and reader goals.
If you cannot determine the owner, reader intent, scope, or authoritative sources, first preserve the uncertainty and report the gap; do not fabricate product decisions or current behavior based on experience.
Authoring workflow
1. Locate the task and document position
Identify whether this is new creation, update, splitting, merging, or structural review. Read the applicable AGENTS.md, CLAUDE.md, CONTEXT.md, document index, and adjacent documents to confirm the repository's existing hierarchy, naming, and link conventions.
If the target document does not exist, treat the task as greenfield documentation: build a candidate document map from code directories, public APIs, configuration schemas, tests, examples, commands, and generated files. First decide whether one entry document or a set of documents divided by owner and reader intent is needed; do not compress the entire code framework into one comprehensive explanation.
Completion criteria: When documentation exists, you already know the target path, parent document, direct children, and applicable local rules; when no documentation exists, you already know the main boundaries of the code framework, the candidate set of documents, and the preliminary owner and authoritative sources for each document.
2. Inventory and classify information
List the facts, explanations, steps, examples, limitations, and historical materials intended to be preserved. Classify by information type, and distinguish between current state, persistent rationale, operational procedures, reference materials, rules, incidents, and generated content.
When a detailed classification table is needed, read references/information-and-ownership.md.
Completion criteria: Every piece of candidate content has a defined information type; different types of material are not mixed into an undefined paragraph.
3. Route facts to canonical owners
Search for an existing owner for each persistent fact. Prefer source code, configuration, schema, generators, and existing decision records as authoritative sources; documentation only owns the explanations, procedures, or stable contracts within its responsibility.
For content that already has an owner, retain only the necessary summary and a link to the owner. If multiple conflicting owners are found, first report the conflict and document the authority issue that needs resolution.
Completion criteria: Every non-trivial fact has exactly one owner; the current document does not duplicate authoritative details from elsewhere.
4. Select the document type based on reader intent
Choose a document type from Tutorial, How-to, Reference, Explanation, ADR, Policy, or Postmortem based on the reader's goal. Do not assign multiple primary types to a file just because it contains a mix of content; split the document when the mixed intent reaches a level that affects navigation or maintainability.
Read references/document-types-and-composition.md for type selection and structural patterns.
Completion criteria: You can state in one sentence "who reads this document for what purpose", and point to a single primary document type.
5. Fix the scope and detail ceiling
Write down the subject, audience, goal, inclusions, exclusions, authoritative sources, and detail ceiling. Limit the document to its own subject, its level, and the responsibilities of its direct children; move lower-level mechanisms, tests, checklists, and implementation details to their owner.
Document types cannot expand the scope. A parent document describes composition, responsibilities, and high-level behavior; child documents own type definitions, parameters, test mechanisms, or concrete operations.
Completion criteria: Every section can answer "how does it serve the current reader goal and scope"; materials outside the boundary already have a destination or link.
6. Form an executable authoring plan
First arrange the prerequisite concepts the reader must know, then arrange the operations, explanations, or reference content that depend on them. Use the structure corresponding to the document type; do not turn the order of investigation, implementation, discussion, or commits into a teaching order.
For large documents, record the section tree, fact owners, section dependencies, target files, exclusions, and acceptance criteria for each section. The plan must allow another agent to complete a local task without redesigning the global structure.
Completion criteria: The reader does not need to jump to later sections to understand necessary terms, prerequisites, or actions in earlier sections; each major paragraph serves a clear question; each plan unit has a unique scope and completion criteria.
7. Choose the execution mode and delegate
The default is the single-agent path. Only open sub-agents when all of the following conditions are met:
- The plan is frozen, with no unresolved conflicts in reader intent, document type, scope, owner, or major structure.
- At least two work units exist that can be read independently, written independently, and validated independently.
- Each work unit has a unique target file or section owner, and tasks will not concurrently edit the same body of text.
- Dependencies are explicitly recorded; facts that need to be shared already have authoritative sources, rather than relying on sub-agents to guess from each other.
- The cost of splitting and merging is lower than the cost of the primary agent continuously carrying the full document context.
When conditions are met, read references/orchestration-and-delegation.md; the primary agent generates a delegation brief and calls sub-agents. The primary agent retains global planning, fact attribution, cross-section linking, merge decisions, and final acceptance. Sub-agents do not redesign the document type, modify other work units, or present unverified facts as conclusions.
When conditions are not met, the primary agent continues writing alone. Single-file local supplements, revisions of a few paragraphs, Reference updates with a single owner, and strongly serial dependencies all belong to the single-agent path.
Completion criteria: A clear choice has been made between single-agent or delegated execution; if delegated, every task has boundaries, dependencies, output format, and acceptance criteria.
8. Write directly about the current contract and observable behavior
Express content using concrete subjects, actions, APIs, options, and results. Write the current state and observable behavior for the reader first, then supplement defaults, limitations, exceptions, rationale, and trade-offs. Clearly distinguish between "must", "default", "recommended", and "may".
Tutorial and How-to can center on minimal examples as explanations; Reference centers on retrievable definitions and boundaries; ADR and Postmortem retain the rationale or timeline they require.
When complete expression rules and validation checklists are needed, read references/writing-and-validation.md.
Completion criteria: The body states maintainable facts, contracts, or steps, not reasoning processes, implementation logs, or vague meta-discourse; outputs from delegated tasks have been collected back to the primary agent.
9. Merge and unify
If sub-agents were used, the primary agent checks each output against the authoring plan. Resolve duplicate facts, terminology drift, section boundaries, cross-links, and style inconsistencies; centrally record unresolved issues rather than letting local agents invent global decisions. Do not merge the sub-agents' process descriptions directly into the body; only merge maintainable results.
Completion criteria: Each delegated unit has a result or a clearly identified blocker; the same fact does not have multiple owners; the global table of contents, links, terminology, and reader paths are consistent.
10. Link, trim, and validate
Remove duplicate facts, hand-copied lists, irrelevant background, and details exceeding the detail ceiling. Link to owners, sub-documents, source code, and decision records using goal-descriptive links. Complete structural and language validation in the order specified by the reference files.
Completion criteria: Owner, type, scope, dependency order, current/historical boundaries, links, and expression rules have all been checked; no unresolved conflicts or uncertainties remain.
Boundaries
Do not turn repository-specific file hierarchies, script commands, word budgets, code block compilation rules, bilingual workflows, or specific terminology into universal rules. Read local project conventions and obey them; this Skill only provides a cross-project stable documentation decision framework.
Do not treat README, architecture.md, or AGENTS.md as fixed universal document types. First determine the reader intent, then follow the project's specific conventions for these carriers.
Final handoff
After completion, briefly state: the document type and reader intent, how canonical owners were handled, the scope boundaries, any links or splits involved, and any factual conflicts that still require a human decision. Do not disguise unresolved issues as the current state.