technical-writing
階層化されたテクニカルライティング標準。Diátaxis の構造、Google developer style の文、STE の指示ルール、Global English の構文。/technical-writing、またはドキュメント、RFC、readme、PR の説明、コミットメッセージを書いたりレビューしたりするときに使う。
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- technical-writing
- description
- 階層化されたテクニカルライティング標準。Diátaxis の構造、Google developer style の文、STE の指示ルール、Global English の構文。/technical-writing、またはドキュメント、RFC、readme、PR の説明、コミットメッセージを書いたりレビューしたりするときに使う。
03 SKILL.md 正文
Technical writing
目標は、疲れたエンジニアが一読で理解できる文章を書くことである。そこへ至る層は 4 つあり、それぞれ問いが 1 つずつある。この文書はどの種類か、文は読者にどう語りかけるか、各文はどれだけの情報を運ぶか、二通りに読める文はないか。4 つすべてを適用する。
層の上位に 3 つのルールがある。
- 働いていない語はすべて削る。 ある語なしでも文が成り立つなら、その語は消す。「In order to」は「to」である。「It is important to note that」は何も言っていない。
- 短い日常語を使う。 「utilize」ではなく「use」。「facilitate」ではなく「help」。「perform」ではなく「do」。長い語は、その長さに見合う精度で対価を払わなければならない。
- ルールが文を悪くするなら、別の方法で文を直すか、そのままにしておく。 ルールは読者に仕える。すべてのルールに従いながら機械が書いたように聞こえる文は、失敗している。
コードベースが語彙表である。実際のシンボル、ファイル、フラグ、コマンドの名前を書き、同義語やその説明を書かない。
専門用語を発明しない。開発者が声に出して言う語を使う。「evacuate」「ratchet」「endgame」ではなく、「move」「delete」「a budget that only decreases」。名前の付いたパターンは、文書が初出時にその意味を述べていれば問題ない。新しい違反語とその置き換えを、unslop の抽象メタファールールへの追加として、diff 付きで返答の中に提案する。そのスキルを編集してはならない。
リズムを変える
層は、文書が何を言うか、各文がどれだけ運ぶかを決める。文書はそれらすべてに従っていても、なお機械が書いたように読めることがある。すべての文が短く刈り込まれ、どこにも見解がなく、具体的なものが何もない。
- 文の長さを意図的に混ぜる。短い文は要点を打ち込む。時間をかける長い文は、事実をその条件や帰結とともに運ぶ。
- 一文一思考は、一文一長さを意味しない。2 つの思考を運ぶ文は分割する。1 つの思考を運ぶ長い文は残す。
- モードが許すところでは見解を持つ。説明はトレードオフを秤にかけるものなので、長所と短所を列挙するのではなく、それをどう考えるかを述べる。リファレンスは乾いたままにする。
- 無味乾燥より具体的に。「schema changes can cause issues」ではなく「a column rename fails the build」。
まずモードを選ぶ(Diátaxis)
1 つの文書、1 つのモード。2 つの問いで選ぶ。内容は行動(doing)に資するか、理解(thinking)に資するか。そして学習に役立つか、仕事に役立つか。
- 行動 + 学習: チュートリアル。
- 行動 + 仕事: ハウツー。
- 理解 + 仕事: リファレンス。
- 理解 + 学習: 説明。
このコンパスは文書全体にも、1 つの文にも使う。
チュートリアル: 実践による学習。 自分は教師である。学習者の成功は自分の仕事であり、学習者の仕事ではない。学習者が何を「学ぶ」かではなく、何を作るかを述べて始める。すべてのステップが目に見える結果を、早く、頻繁に生む。何が見えるはずかを伝える。期待される出力、プロンプトの変化、ログの行。説明は 1 節とリンク 1 つに削る。教えるための中断は授業を壊す。具体的であり続ける。「we」として、命令で書く。「First, do x. Now, do y.」
ハウツー: 目標へのステップ。 機械が実行できる操作ではなく、人が抱える問題を解く。能力があると仮定する。教えることは飛ばす。行動のみ。脱線なし、背景なし、完全性のための完全性なし。それらはリンクで代える。分岐と判断を許す。「If you want x, do y.」ガイドの名前はタスクで付ける。「Radar array calibration」ではなく「How to calibrate the radar array」。
リファレンス: 参照のための事実。 記述する。記述だけをする。指示なし、説得なし、意見なし。乾いていて、完全で、確かであること。事実、選択肢、制限、エラーを、保険をかけずに述べる。記述対象の構造を映し、コードと文書を一緒にたどれるようにする。読者が期待する場所に素材を置く。可能ならコードから生成し、真であり続けるようにする。
説明: 理解と理由。 境界のある 1 つのトピックで、製品から離れても読める。各タイトルは、先頭に暗黙の「About...」を付けても耐えられるべきである。実際の「なぜ」の問いに根ざす。文脈を与える。設計上の決定、歴史、制約、代替案。意見はここでは許され、他のどこでも許されない。
モードを混ぜない。チュートリアルの中にリファレンスの表を入れない、リファレンスの中にチュートリアルの手取り足取りを入れない、ハウツーの中で論争しない。代わりに分割してリンクする。
出典: diataxis.fr、2026-07-18 取得。
読者に向けて文を書く(Google developer style)
- 読者に「you」で、現在形で語りかける。「Will」は本当に後で起きることにだけ使う。
- 誰が何をするかを言う。「is checked」ではなく「the compiler checks」。受動態は、行為者が不明か重要でないときだけ許される。
- 指示は命令として書く。「Click Submit.」事実は平易に述べる。「should be done」は決して使わない。
- 条件を指示の前に置く。「To delete the document, click Delete.」読者は該当しないものを飛ばす。
- 一般的なケースを先に置く。例外は後。
- 知識のある友人のように聞こえること。バズワードなし、比喩表現なし、指示に「please」なし、手順に「simply」「easy」「quickly」は決して使わない。簡単なら、読者はここにいない。
- 予告しない(「we will soon support...」)。連続する文を同じ句で始めない。
- リンク先がどこかを言う語でリンクする。ページタイトルか短い説明。「click here」は決して使わない。ページ外へのリンクより、ページ上の文脈の一文を優先する。
- 見出しは主題だけでなく要点を運ぶ(「Modes」ではなく「Pick the mode first」)。センテンスケース。タスクの見出しは動詞句だけにする(「Create an instance」)。概念の見出しは名詞句。ページに h1 は 1 つ、レベルを飛ばさない。
- 順序には番号付きリスト、それ以外はすべて箇条書き。リストは完全な文で導入する。項目は並列に保つ。
- コードはコードフォントに。UI 要素は太字に。シリアルコンマを使う。「etc.」は落とし、リストが一部であることを最初に言う。
出典: developers.google.com/style、2026-07-18 取得。
文を 1 つずつ読み込ませる(STE ルール)
- 1 文につき指示 1 つ。それ以外はすべて 1 文につき思考 1 つ。
- 約 20 語を超える指示と、約 25 語を超えるその他の文は分割する。
- 警告や条件は、それが守るステップの前に置く。「If hot oil touches your skin, injuries can occur.」
- 「the」と「a」を残す。「Remove backup file」は二通りに読める。「Remove the backup file」は一通りに読める。
- 各語に 1 つの意味と 1 つの役割を与え、それを守る。「check」が点検を意味するなら、抑止の意味でも使わない。
- 行動ごとに 1 語を選び、それを貫く。ここでは「start」、あそこでは「initiate」ではなく、「start」。
- 手順は直接の命令として書き、決して叙述にせず、決して受動態にしない。「the component must be installed」ではなく「Install the component」。
- 可能なところでは「-ing」の語を避ける。文法上の役割を多く担いすぎ、誤読を生む。
出典: asd-ste100.org(Issue 9、2025)、2026-07-18 取得。番号付きルールと辞書は仕様 PDF にある。上の原則は、他へ持ち運べる中核である。
二通りに読める文を残さない(Global English)
- 「only」や「not」のような語は、それが変える語の隣に置く。「only fails on growth」と「fails only on growth」は違うことを言う。
- 長い名詞の連なりを分解する。「the proto import budget check script」は「the script that checks the proto-import budget」になる。
- すべての「it」「they」「this」が 1 つの明白なものを指すようにする。迷ったら名詞を繰り返す。節全体を指すために「this」や「which」を決して使わない。
- 動詞を落とさない。「Phase 1 moves the converters and Phase 2 the runtime」は Phase 2 に動詞がない。動詞を与える。
- 構造を示す小さな語を残す。「Ensure that the switch is off」は、文の解釈を一通りにするので「that」を残す。明快さを語数と決して交換しない。
- 誤読を防ぐなら、並列の中で冠詞を繰り返す。2 つのものであるなら、「the client and host」ではなく「the client and the host」。
- 文が二通りにまとまり得るときは、「and」や「or」がどの部分を結ぶかを言う。「Both...and」「either...or」「if...then」はコストのかからない曖昧さ解消手段である。
- セミコロンではなくピリオドを使う。em ダッシュは新しい文に置き換える。
- 括弧内のテキストは、完全な文法単位か、それ自体で 1 文にする。「(s)」で複数形を決して作らない。
- スラッシュなし。「a/b」や「and/or」ではなく「a, b, or both」と書く。
- 各事物を、どこでも 1 つの名前で呼ぶ。1 つのものを「the gate」「the ratchet」「the budget check」と呼ぶ文書は、3 つのものを教えている。編集の間に、変わっていない文を言い換えるのも同じ代償を払う。変わっていないものをかき回さない。
- 慣用句、口語表現、ラテン語の略語、メタファーは避ける。非ネイティブの読者、翻訳者、エージェントはいずれも、平易な構文を最もよく解析する。
出典: Kohl, The Global English Style Guide(SAS Press)。ガイドライン本文は Internet Archive と SAS のサンプル章から 2026-07-18 に取得。
文体とリポジトリ固有の事項
- このスキルが触れるすべての文書に unslop スキルを適用する。そのスキルがスロップパターンのカタログを所有する。AI 語彙、フィラー、保険をかける表現、書式上の痕跡。
- PR の説明とコミットメッセージも文章である。Diátaxis を除くすべての層がそれらに適用される。PR 本文は、レビュアーが 1 分以内に読めるブリーフィングである。swarm のログ、SHA の一覧、メトリクスの表を貼り付けない。リンクする。
- 製品の UI 文字列はドキュメントではない。それらには自分の製品のコピーガイドラインを使う。
- コードスニペットはタブでインデントする。実際のパスと実際のシンボルを書く。件数やツリーに関するすべての主張を、それを取り込むコミット時点で真にし、それを再生成するコマンドを含める。
実例
修正前:
Configuration of the proto import ratchet budget script parameters is performed via budget.json. Note that it's important to remember that running with --write, which updates the committed budget to reflect the current count, should only be done when lowering it. If exceeded, CI fails.
修正後:
budget.mjsreads the committed budget frombudget.jsonand counts the files that import protos. If the count exceeds the budget, CI fails. Runbudget.mjs --writeonly to lower the budget.
レビューチェックリスト
このスキルが対象とするあらゆる文章に適用する。項目 1 は文書集合にのみ適用される。
- 各ファイルは 1 つの Diátaxis モードで、モードが接するところにリンクがあるか。
- すべての指示が、条件を前に置いた命令として書かれているか。
- 2 つの指示または 2 つの思考を運ぶ文はあるか。分割する。
- 意味を失わずに削れる語はあるか。削る。
- 「only」はそれが変える語の隣にあるか。すべての「it」は 1 つのものを指しているか。すべての節は動詞を保っているか。
- 各事物は文書全体でちょうど 1 つの名前を持つか。
- 開発者はこれらの語を声に出して言うか。発明されたメタファーや気取った同義語を、平易な語か実際のシンボル名に置き換える。
- すべてのシンボル、パス、件数はこのコミット時点で実在し、件数を再生成するコマンドが付いているか。
04 同仓库更多 Skills
why
「なぜ X はこの動きなのか」「なぜ Y を選んだのか」、設計の根拠説明、リグレッション、ポストモーテム、データに裏付けられたしきい値に使う。利用可能な MCP を発見し、各証拠カテゴリ(ソース管理、issue トラッカー、長文ドキュメント、リアルタイムチャット、インフラ可観測性、エラートラッキング、プロダクト分析ウェアハウス)を並列で問い合わせ、決定とトレードオフについて引用付きの読み解きを返す。実行時の振る舞いには how を使う。
what-did-i-get-done
ユーザーが指定した期間に自分が作成したコミットを、簡潔な状況報告に要約する
unslop
あらゆる文章から AI の痕跡を削る。常に適用しなければならない。
typescript-best-practices
TypeScript のベストプラクティス。.ts または .tsx ファイルを読むか編集するときに使う。
thermo-nuclear-code-quality-review
抽象化の質、巨大ファイル、スパゲッティ条件分岐の増殖について、極めて厳格な保守性レビューを行う。thermo-nuclear なコード品質レビュー、thermonuclear レビュー、深いコード品質監査、または特に厳しい保守性レビューに使う。
teach
ある作業のまとまりを平易に説明し、人が本当に理解できるようにする。`how` と `why` のスキルを実行し、その発見を 1 つの明快な説明に織り込む。'これを教えて'、'X を本当に理解する手助けをして'、'この変更またはサブシステムを説明して'に使う。