cursor/plugins

technical-writing

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

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/cursor/plugins --skill technical-writing

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

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.
同じリポジトリから

関連する Skills

すべての Skills