technical-writing-workflow

Technical writing workflow

Use this skill when the user asks to write, rewrite, improve, audit, explain, teach, document, or publish technical material. Treat it as a workflow with checks, not as a prose vibe.

Core rule

Open the subject up without making it shallow.

Every important explanation must name:

1. the object or behavior being described
2. the method, mechanism, or actor that changes it
3. the evidence that supports the claim
4. the boundary the claim is allowed to cover

Serial before parallel

Serialize meaning. Parallelize collection.

Do these serially before drafting:

1. Define the reader and use case.
2. Define scope and exclusions.
3. Build the ontology table.
4. Decide the argument order.
5. Write chapter or section contracts.
6. Resolve source contradictions.

Then parallelize:

• source packets
• paper cards
• glossary entries
• examples
• diagrams
• exercises
• tables
• reference checks
• local fact checks
• counterexamples and failure modes

Return to serial work for:

• synthesis
• final claim strength
• voice and terminology
• cross-references
• final layout or render inspection

The workflow

1. Intake

Write a short brief before drafting:

• audience
• task the reader should perform after reading
• source surface
• deliverable format
• deadline or depth target
• claim-risk level

If any of these are unknown, make a conservative assumption and state it briefly.

2. Source audit

Separate sources into evidence classes:

• primary paper or official documentation
• benchmark or measurement artifact
• code or reproducibility artifact
• technical blog or explainer
• social post or pointer
• local note or capture

Do not let a pointer carry a claim that belongs to a paper, code artifact, or measurement.

3. Ontology table

For each major topic, create this table before drafting:

Topic:
Object:
Method:
Resource or behavior changed:
Evidence:
Boundary:
Common beginner mistake:
Best example:

This table is the backbone. If it is confused, the prose will be confused.