technical-writing

v2026.09.24

Write prose in "Simplified Technical English". This applies to documentation, READMEs, commits, pull request, plans and release notes. It does not apply to code, identifiers, marketing copy, essays, or anything that needs a voice.

GitHub
Install command
npx skhub add frappe/technical-writing
Markdown
SKILL.md

Rules

WORDS

  • Use one name for one thing. Do not call the same item by two different names.
  • Use the short common word: start (not begin/commence/initiate), use (not utilize/leverage), help (not facilitate), make sure (not ensure), before (not prior to), after (not subsequent to), about (not regarding/concerning), get (not obtain/acquire), show (not demonstrate), also (not additionally/furthermore/moreover), now (not currently/at this time), many (not numerous), first (not initial), enough (not sufficient), try (not attempt), rest (not remainder), do (not implement), called (not referred to as), because (not due to the fact that), for (not for the purpose of), until (not until such time as), except (not with the possible exception of).
  • Give each word one meaning. "fall" means to move down, not to decrease.
  • No marketing adjectives: seamless, robust, powerful, cutting-edge, effortless, world-class, next-generation, revolutionary.
  • No euphemism. Say what happened. "We laid off 3,000 employees", not "we reduced headcount".
  • Cut the qualifiers: a bit, a little, sort of, kind of, rather, quite, very, too, pretty much, in a sense, arguably, decidedly. Each one costs the reader some trust.
  • Cut the announcement phrases: "it is important to note that", "it should be pointed out that", "it is interesting that". If it should be pointed out, point it out.
  • American spelling.

VERBS

  • Active voice. "the parser reads the file", not "the file is read by the parser".
  • Use a verb for an action. "analyze the log", not "perform an analysis of the log".
  • Do not hide the action in a concept noun. "most users fail at this step", not "the common reaction is failure".
  • Use the precise verb. Not "the service stepped down" but "the service exited", "the service crashed" or "the service was stopped".
  • Drop the appended preposition when the verb works alone: "start" (not start up), "free" (not free up), "order" (not order up).
  • No stacked auxiliaries. Not "it is important to note that this may help to improve". Write "this improves X".
  • No "-ing" main verb where a simple tense works.

ADVERBS AND ADJECTIVES

  • Delete the adverb that repeats the verb: "blared loudly", "clenched tightly", "grinned widely".
  • Delete the adjective that repeats the noun: "tall skyscraper", "unexpected surprise".
  • Keep an adjective only when it does work the noun does not do.

SENTENCES

  • One instruction per sentence. Max 20 words (instruction), max 25 (descriptive).
  • Break a long sentence into two. There is no minimum sentence length.
  • Do not stack nouns. "communication facilitation skills development" is not a phrase. Three nouns in a row is a defect.
  • No contractions. Use articles: a, an, the, this, these.
  • Do not overstate. An exaggerated claim makes every other claim suspect.

PUNCTUATION

  • No semicolons. Write two sentences. (Note: the em dash is not banned by STE, only the semicolon is — add "no em dash" yourself if you want it gone.)
  • No exclamation points.
  • Use the colon to introduce a list.

STRUCTURE

  • One topic per paragraph, max six sentences. Short paragraphs put air around the text.
  • For steps, use a numbered vertical list, one action per item, imperative form. Put a condition before its command.
  • Explain in linear sequence. The reader knows nothing. Start with the one fact needed to understand the second sentence, then widen. No leaps, no implied steps.
  • Signal a change of direction at the start of the sentence, not the end: but, however, instead, then, next, first.
  • Decide one point before you write. Cover a narrow subject well and stop.
  • Stop when you are done. No summary that repeats what the text already said.

REVISE

  • The first draft is not the deliverable. Most first drafts lose half their words without losing information.
  • Pass over each sentence and ask: is every word doing new work? Can I say this with less?
  • When a sentence resists every fix, delete it. It was doing an unnecessary job.
  • Read the text in order and check that each sentence follows from the one before it.

Write only the requested text. No preamble, no summary, no closing remarks.

Discovery
Tags

No tags published for this skill.

Version
Latest version metadata

Version

v2026.09.24

Published

Sep 24, 2026

Category

Uncategorized

License

Not specified

Source path

skills/technical-writing

Default branch

main

Latest commit

f9cac45

Tree SHA

56ea14b