# Technical Writing

> Layered technical-writing standard for docs, RFCs, READMEs, PR descriptions, and commit messages. Diátaxis structure, Google developer style sentences, STE instruction rules, Global English syntax. Use for technical-writing or when writing or reviewing those surfaces.

- Skill: `shipshitdev/technical-writing` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds add shipshitdev/technical-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shipshitdev/technical-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: shipshitdev (https://skillmd.com/u/shipshitdev)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/shipshitdev/technical-writing

---


# Technical writing

The goal is writing a tired engineer understands on the first read.
Four layers: what kind of document this is, how sentences address the
reader, how much each sentence carries, and whether any sentence
reads two ways.

Companion to `docs` (repo-convention docs writer) and `deslop`
(prose-tell catalog). Apply
`references/prose-slop.md` from the selected `deslop` skill directory to every doc this skill
touches.

## Authorized Scope

Apply this engine only within the user's requested task and existing explicit
authorization. Loading or delegating to it grants no additional authority.
Preserve report-only restrictions and the caller's target, host, provider, and
cost limits. Existing approval satisfies a gate only for the same actions and
scope; obtain approval before expanding them. Forward these limits to delegates.

## Contract

Inputs:

- A doc, RFC, README, PR description, or commit message to write or
  review

Outputs:

- The rewritten surface, in one Diátaxis mode when the artifact is a
  document

Creates/Modifies:

- The named prose files or git metadata the caller asked for

External Side Effects:

- None beyond those writes

Confirmation Required:

- None for drafting. Confirm before committing.

Delegates To:

- File pointer: `references/prose-slop.md` from the selected `deslop` skill directory

## Rules above the layers

- Cut every word that does no work.
- Use the short, everyday word.
- When a rule makes a sentence worse, fix the sentence another way.
- The codebase is the word list. Write the real symbol, file, flag,
  or command name.

## Pick the mode first (Diátaxis)

- Action + learning: **tutorial**.
- Action + work: **how-to**.
- Understanding + work: **reference**.
- Understanding + learning: **explanation**.

Do not mix modes. Split and link instead. Source: diataxis.fr.

**Tutorial.** Open by saying what the learner will build. Every step
produces a visible result. Write as "we", in commands.

**How-to.** Solve a problem a person has. Assume competence. Action
only. Name the guide by the task.

**Reference.** Describe. Only describe. Mirror the structure of the
thing described.

**Explanation.** One bounded topic. Anchor on a real why. Opinion is
allowed here and nowhere else.

## Sentences (Google developer style)

Talk to the reader as "you", present tense. Say who does what.
Instructions as commands. Condition before the instruction. Common
case first. Sentence-case headings. Numbered lists for sequences.
Source: developers.google.com/style.

## Load one thought at a time (STE)

One instruction per sentence. Split instructions longer than about 20
words. Keep "the" and "a". One word per action, then keep it. Source:
asd-ste100.org (Issue 9, 2025).

## Leave no sentence open to two readings (Global English)

Keep "only" and "not" next to the word they change. Break up long
noun strings. Make every "it", "they", and "this" point at one
thing. No slashes. Call each thing by one name. Source: Kohl, The
Global English Style Guide.

## Voice

- PR descriptions and commit messages are writing too. Every layer
  except Diátaxis applies to them.
- Product UI strings are not documentation.
- Write real paths and real symbols. Make every count true at the
  commit that lands it.

## Review checklist

1. Is each file one Diátaxis mode?
2. Is every instruction a command, with its condition in front?
3. Does any sentence carry two thoughts? Split it.
4. Can any word be cut? Cut it.
5. Is "only" next to the word it changes?
6. Does each thing have exactly one name?
7. Would a developer say these words out loud?
8. Are symbols, paths, and counts real at this commit?

## Technical Writing procedure

Read [technical-writing procedure](references/technical-writing-procedure.md) when running this workflow.
Apply the authorized scope and mode of this entry point to every step.
Resolve other skills through this distribution’s active catalog; resolve
resources relative to the installed skill directory.