# TS Technical Writing

> Technical writing reference for docs, plans, reviews, prompts, and user-facing artifacts.

- Skill: `tstelzer/ts-technical-writing` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add tstelzer/ts-technical-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tstelzer/ts-technical-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tstelzer (https://skillmd.com/u/tstelzer)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tstelzer/ts-technical-writing

---


# Technical Writing

## How to use

- Always read this file first.
- Treat the bullets below as the canonical short form.
- Read the local detail docs that match the artifact.
- For software documentation, also read `skill: ts-principles`, especially `integrated documentation`.

## Principles

### write for a reader doing a job

- Name the reader before writing.
- Name what the reader wants to do, decide, fix, or understand. In an error, name the failed operation and subject.
- Include only what helps that reader complete the job. Preserve safe cause messages and diagnostic context.
- Respect the reader's trust boundary. Do not expose secrets or restricted internals.
- State a corrective action only when it is known to apply.
- State assumed knowledge, prerequisites, and non-scope when they prevent wrong expectations.

[Details](audience.md)

### choose the artifact shape before writing

- Tutorial: teach by doing.
- How-to: complete one task.
- Reference: describe facts, contracts, parameters, commands, fields, and errors.
- Explanation: explain context, reasons, tradeoffs, and design.
- Do not mix shapes by accident.

[Details](artifact-shape.md)

### put the answer first

- Start with the action, decision, result, or summary.
- Put background after the thing the reader came for.
- Use headings that say what is inside the section.
- Use the first paragraph as the fastest useful path through the artifact.

[Details](structure.md)

### write plain prose at a useful density

- Use common words when they carry the same meaning.
- Prefer active voice.
- Prefer strong verbs over noun phrases.
- Optimize for reading time before word count.
- Split a sentence when it carries several decisions, causes, or conditions.
- Keep exact code symbols, API names, protocol terms, and established domain terms.
- Replace workflow vocabulary with words the reader uses.
- Define an unfamiliar term on first use when code or context does not make it clear.
- Cut filler, hedges, throat-clearing, and repeated setup.
- Keep one idea per paragraph.

[Details](prose.md)

### prefer examples over abstractions

- Show the command, code, config, input, output, error, or decision.
- Show errors with the failed operation, subject, safe cause, and any known corrective action.
- Make copyable examples correct.
- Put examples near the rule they prove.
- Use realistic values, not fake secret-shaped strings.

[Details](examples.md)

### make content scannable

- Use bullets for sets of peers.
- Use numbered lists for ordered steps.
- Use tables for structured comparison.
- Keep list items parallel.
- Start procedure steps with imperative verbs.

[Details](structure.md)

### remove llm-isms

- Remove generic hype, fake helpfulness, and empty transition phrases.
- Do not say a task is simple, easy, seamless, powerful, robust, or crucial unless the claim is concrete and proven.
- Do not explain that you are explaining.
- Do not end with boilerplate invitations when the answer is done.
- Treat feedback as an edit instruction, not artifact content.
- Remove exclusions that do not prevent a plausible reader action.

[Details](llm-isms.md)

### treat docs as contracts

- Keep docs next to the surface readers use.
- Document why, constraints, invariants, failure modes, and contracts.
- Do not repeat what names, types, schemas, and tests already say.
- Update docs with behavior.
- Delete stale docs.

[Details](maintenance.md)

## Source Material

This skill distills:

- Diataxis: https://diataxis.fr/
- Google Technical Writing One: https://developers.google.com/tech-writing/one
- Google Developer Documentation Style Guide: https://developers.google.com/style
- Microsoft Writing Style Guide: https://learn.microsoft.com/en-us/style-guide/welcome/
- Digital.gov Plain Language Guide: https://digital.gov/guides/plain-language
- Nielsen Norman Group, How Users Read on the Web: https://www.nngroup.com/articles/how-users-read-on-the-web/
- Write the Docs, Style Guides: https://www.writethedocs.org/guide/writing/style-guides/