cursor/plugins

technical-writing

Layered technical-writing standard: Diátaxis structure, Google developer style sentences, STE instruction rules, Global English syntax.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/cursor/plugins --skill technical-writing

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

Technical writing

Write so a tired engineer understands on the first read.

  • Cut every word that does no work.
  • Use the short, everyday word: "use", not "utilize".
  • When a rule makes a sentence worse, fix the sentence another way or leave it alone.
  • Write the real symbol, file, flag, or command name, not a synonym or a description of it.
  • Don't invent jargon. Use the words a developer would say out loud. Say what a named pattern means the first time.

Vary the rhythm

  • Mix sentence lengths. Split the sentence that carries two thoughts. Keep the long sentence that carries one.
  • Have a view in explanation. Keep reference dry.
  • Be specific. Not "schema changes can cause issues" but "a column rename fails the build".

Pick the mode first (Diátaxis)

One document, one mode. Don't mix modes. Split and link instead.

  • Tutorial: learning by doing. Say what the learner will build. Every step produces a visible result, and you say what they should see. Explanation gets one clause and a link.
  • How-to: steps to a goal. Solve the reader's problem. Assume competence. Action only. Allow forks. Name the guide by the task.
  • Reference: facts for lookup. Only describe. Be dry, complete, and sure. Mirror the structure of the thing described.
  • Explanation: understanding and why. One bounded topic. Give context: design decisions, history, constraints, alternatives. Opinion is allowed here and nowhere else.

Write sentences to the reader (Google developer style)

  • Talk to the reader as "you", in the present tense.
  • Say who does what. Passive is fine only when the actor is unknown or beside the point.
  • Write instructions as commands. Put the condition before the instruction and the common case first.
  • No buzzwords, no figurative language, no "please", and never "simply", "easy", or "quickly" in a procedure.
  • Don't pre-announce, and don't start consecutive sentences with the same phrase.
  • Link with words that say where the link goes.
  • Headings carry the point, in sentence case. One h1 per page, no skipped levels.
  • Numbered lists for sequences, bullets for everything else. Introduce a list with a complete sentence. Keep items parallel.
  • Code goes in code font. UI elements go in bold. Use serial commas. Drop "etc.".

Make statements load one at a time (STE rules)

  • One instruction per sentence. One thought per sentence everywhere else.
  • Split instructions longer than about 20 words and other sentences longer than about 25.
  • Put the warning or condition before the step it guards.
  • Keep "the" and "a".
  • Give each word one meaning, and pick one word per action.
  • Write procedures as direct commands, never as narration and never in the passive.
  • Avoid "-ing" words where you can.

Leave no sentence open to two readings (Global English)

  • Keep words like "only" and "not" next to the word they change.
  • Break up long noun strings.
  • Make every "it", "they", and "this" point at one obvious thing. Never use "this" or "which" to point at a whole clause.
  • Don't drop verbs, or the small words that show structure, such as "that".
  • Repeat the article in a series when it prevents a misread. Say which parts "and" or "or" joins.
  • Use periods, not semicolons or em dashes. No slashes, and no "(s)". Make text in parentheses a full grammatical unit.
  • Call each thing by one name, everywhere.
  • Skip idioms, colloquialisms, Latin abbreviations, and metaphors.

Voice and repo specifics

  • Apply the unslop skill to every doc this skill touches. That skill owns the slop-pattern catalog: AI vocabulary, filler, hedging, formatting tells.
  • PR descriptions and commit messages are writing too. Every layer except Diátaxis applies to them. A PR body is a briefing that a reviewer can read in under a minute. Do not paste swarm logs, SHA lists, or metric tables. Link them.
  • Product UI strings are not documentation. Use your product's copy guidelines for those.
  • Indent code snippets with tabs. Write real paths. Make every count or tree claim true at the commit that lands it, and include the command that regenerates it.
aus demselben Repository

Weitere Skills

Alle Skills