Technical Writing Skill

Technical Writing

Write clear technical prose with rigorous quality review.

When to Use

Writing technical documentation, design docs, or READMEs
Drafting blog posts or technical reports
Writing research papers or whitepapers
Any technical writing that needs to transfer ideas clearly
Existing draft needs systematic improvement

Don't use for: Quick notes, informal messages, or throwaway text.

Core Principles

Every sentence serves one goal: transfer ideas from author to reader.

Give away the punchline - State your point upfront, don't bury it
Topic sentences - First sentence of each paragraph enables scanning
Active voice - "The system handles X" not "X is handled by the system"
Consistent terminology - Same concept uses same term throughout
Concrete before abstract - Examples before generalizations
Figure-first explanations - Lead with diagrams, standalone captions

Quality Rubric

Review occurs in three sequential layers. Each layer has specific focus.

Layer 1: Structure

| Criterion | Requirement | |-----------|-------------| | Main point upfront | Reader knows the point within first paragraph | | Logical flow | Each section follows naturally from the previous | | Section balance | No section dominates inappropriately | | Scannable | Headers and topic sentences tell the story | | Completeness | No obvious gaps in the argument or explanation |

Layer 2: Clarity

| Criterion | Requirement | |-----------|-------------| | Active voice | No passive constructions obscuring agency | | Topic sentences | First sentence of each paragraph states main point | | Consistent terminology | Same concept uses same term throughout | | No weasel words | Avoid "clearly," "obviously," "simply," "just" | | Paragraph coherence | 3-5 sentences, single idea, transition words | | Concrete examples | Abstract claims grounded in specifics |

Layer 3: Evidence

| Criterion | Requirement | |-----------|-------------| | Claims supported | Every claim has evidence or reasoning | | Examples work | Code samples run, commands execute | | Figures standalone | Captions explain without requiring text | | Links valid | External references resolve | | Accuracy | Technical details correct and verifiable |

Document Types

The same principles apply across formats, with emphasis shifts:

| Type | Emphasis | Structure | |------|----------|-----------| | Documentation/README | Scannable, working examples | What → Why → How → Reference | | Blog/Article | Hook, narrative, examples | Hook → Problem → Solution → Implications | | Design Doc | Context, alternatives, tradeoffs | Context → Goals → Design → Alternatives → Plan | | Research Paper | Contribution clarity, evidence rigor | Problem → Contribution → Approach → Evaluation | | Technical Report | Completeness, actionable conclusions | Summary → Findings → Analysis → Recommendations |

Inputs

Before drafting:

Topic and scope
Target audience (who is reading this?)
Key points to convey
Supporting material (code, diagrams, data)

Output Schema

{
  "topic": "string",
  "audience": "string",
  "status": "DRAFT | REVIEWED | COMPLETE",
  "sections": [
    {
      "heading": "string",
      "content": "string"
    }
  ],
  "review_history": {
    "structure": "PASS | REVISE",
    "clarity": "PASS | REVISE",
    "evidence": "PASS | REVISE"
  }
}

Recording Reviews

Post review progress to jwz:

jwz post "writing:<topic>" --role alice \
  -m "[alice] REVIEW: <topic>
Layer: STRUCTURE | CLARITY | EVIDENCE
Verdict: PASS | REVISE
Notes: <specific feedback>"

Reference

This skill distills principles from authoritative sources:

Foundational

Strunk & White, The Elements of Style
Steven Pinker, The Sense of Style
Joseph Williams, Style: Toward Clarity and Grace

Technical Writing

Clear Exposition

Distill.pub - Exemplar of visual, interactive explanation

Agent Skills: Technical Writing

Skill Files