technical-writing

テクニカルライティング

概要

テクニカルドキュメントのハウススタイルです。ルールは英語で記述されていますが、ドキュメントはそれぞれの言語を保ちます。オランダ語のドキュメントはオランダ語で書かれ、レビューされます。構造と真実性に関するルールはどの言語でも適用されますが、references/style.md の語彙リストは英語固有のものであり、他の言語にはそれぞれ独自のものがあります。中核となる原則: ドキュメントは、現時点で検証済みの動作を、結論を先に述べ、すべての主張が情報源までたどれる形で記述し、すべての事実はちょうど一箇所にのみ存在する。 薄いドキュメントは、誇張されたドキュメントよりも優れています。

これらのルールはドキュメントを規定するものであり、チャットの返信を規定するものではありません。長さとセクションに関するルールは、流れる文章に適用されるものであり、このファイルのような参照リストには適用されません。

いつ呼び出すか

あらゆるテクニカルな文章に対してこのスキルを読み込み、その上で対応するドキュメントタイプのスキルを読み込んでください。これらはルーティングのヒントであり、各スキル自身の本文が権威です。

リポジトリが定期的にドキュメントを生成する場合は、その呼び出しをプロジェクトメモリに記録してください。CLAUDE.md またはそのプラットフォームにおける同等のファイルに 1 行記載し、そこでのあらゆるテクニカルな文章に対してこのスキルを読み込むようエージェントに指示します。

タスク	併せて読み込むもの
提案、RFC、設計ドキュメント、仕様、移行計画	writing-design-docs
決定の記録、ADR、決定ログのエントリ	recording-decisions
変更履歴のエントリ、リリースノート、「何が出荷されたか」	writing-changelogs
ランブック、セットアップガイド、手順、トラブルシューティングのエントリ	writing-runbooks
トラッカー項目: エピック、ストーリー、タスク、バグレポート、スパイク、受け入れ基準	writing-issues
移行または非推奨化のガイド	writing-runbooks
ポストモーテム、インシデントレポート、根本原因分析	writing-postmortems
既存の、ドキュメントが不十分なシステムの文書化、コードに対する古いドキュメントの再接地	documenting-legacy-codebases
プロセス、ライフサイクル、インタラクションの図、ビジネスロジックの作図	diagramming-processes
API リファレンス: エンドポイント、メッセージペイロード、DTO、CLI コマンド、ファイル形式、Webhook	documenting-contracts
他人の文章のレビューや書き直し、あらゆるドキュメントを届ける前の最終パス	reviewing-technical-prose

非目標

• マーケティングコピー、ソーシャル投稿、UI のマイクロコピーを規定するものではありません。references/truth.md の真実性に関するルールのみが、それらにも依然として拘束力を持ちます。
• 内容を決定するものではありません。何が真実かは情報源からもたらされるものであり、スタイルからもたらされるものではありません。
• 独自の慣習に従っている既存のドキュメントを再スタイル化することを許可するものではありません。以下の優先順位ルールを適用してください。
• ドキュメントを「パンチの効いた」「説得力のある」「納得させる」ものにするという要求に屈するものではありません。説得するのは数字であり、文体はあくまで平明に保ちます。

起草前の必須チェックポイント

新しいドキュメントまたは実質的なセクションを起草する前に、作業ノートに以下を導き出して記述してください:

種別: <規範的|記述的|歴史的|ランブック|リファレンス> | 読者: <誰> | 目的: <読者が達成すべき動詞> | 非目標: <これが意図的に扱わないもの>

要求、情報源、リポジトリのコンテキストから各フィールドを埋めてください。結果を実質的に変えない場合は、安全な仮定を述べて続行してください。未知の事項が読者、実質、範囲を変える場合にのみ質問してください。チェックポイントを完成させるために事実を捏造してはなりません。そのスキーマが要求しない限り、完成したドキュメントにチェックポイントを挿入しないでください。

まず読み、それから書く

一行を書く前に:

1. 同じディレクトリ内の比較可能なドキュメントを最大 2 つ読み、その構造、トーン、慣習を採用してください。比較可能なドキュメントが 2 つ未満しかない場合は、利用可能なすべての例を読み、その上でリポジトリレベルの慣習を使用してください。ディレクトリが新しいからといってブロックしないでください。
2. ドキュメントを索引化する README.md があるか確認してください。存在する場合は、新しいドキュメントをそれに追加してください。
3. そのトピックがすでにどこかに存在しないか確認してください。所有者を拡張する方が、その傍らに競合するドキュメントを新たに始めるよりも、ほとんどの場合優れています。

ルールの優先順位

指示が競合する場合は、次の順序で適用します。

1. 真実性、安全性、歴史的完全性に関するルール。
2. 使用中のドキュメント種別スキルに明記された例外。
3. 以下に示す共通のハードルール。
4. 明示されたスキーマと、対象ディレクトリの規約。
5. references/style.md にある共通のスタイル設定。

既存の慣行は、より上位のルールで決着しない選択肢のみを左右します。出典の明示を弱めたり、確定した履歴を書き換えたり、検証されていない作業を出荷済みとして扱ったりすることはできません。ドキュメント種別の例外は、それがどのルールを曲げるのか、また例外の境界を明示しなければなりません。

著者が表明したスタイルの選択は、共通のスタイル設定よりも優先され、それ以外には及びません。著者が自分の声に手を加えないでほしいと述べた場合、スタイル調整はそこで止まります。真実性、安全性、履歴は、誰が反対しようとも拘束力を持ち続けます。

編集する前にドキュメントを分類する

編集ルールは種類ごとに異なります。「コードに合わせてドキュメントを更新する」は、5 種類のうち 2 種類では明確に誤りです。

種類	例	編集ルール
規範	アーキテクチャ原則、契約、スタイルガイド	コードが契約に違反している場合でも、契約を骨抜きにしてはいけません。違反を記録します。契約自体が削除または改名された概念を挙げている場合にのみ編集します。
記述	フロー、コンポーネントドキュメント、状態機械	コードに正確に合わせて更新します。名前ではなく実装に対して検証します。
履歴	変更履歴、旧仕様、意思決定ログ、適用済みマイグレーション	履歴を決して書き換えません。不一致を指摘し、新しいエントリで置き換えます。
ランブック	運用、トラブルシューティング、リリース手順	実態に合わせて更新します。すべての手順は実際に実行されたものでなければなりません。
リファレンス	API ドキュメント、設定リファレンス、索引	網羅的であること。すべてのキー、すべてのフラグを、デフォルト値と Usage 列とともに記載します。

ドキュメント全体が削除された何かを説明している場合でも、ファイルを削除しないでください。1 行のバナー（"> NOTE: describes removed component X; see Y"）で廃止済みと示し、削除はオーナーに委ねます。

ハードルール

すべてのドキュメントにおいて、交渉の余地はありません。

• em ダッシュ、en ダッシュ、-- ダッシュは使わない。 カンマ、コロン、セミコロン、ピリオド、括弧、または補足を示す記号としてスペース付きの - を使います。通常のハイフンは範囲（2026-2030）に使います。納品前に 3 つの形式すべてを確認します。
• ドキュメント内に変更履歴セクションや「最終更新」フィールドを置かない。 これは文単位でも当てはまります。現在の動作を説明し、以前の動作は決して説明しません。「この手順は手動チェックに取って代わった」は、手順書ではなくマイグレーションドキュメントやリリースノートに属します。
• 文章、コメント、名前、文字列に、納品の経緯をナラティブなステータスとして記載しない: フェーズ、タスク ID、チケットキー、SHA、作業がどのように納品されたかを述べるだけの計画参照は禁止です。固定したコミットは、主張の証拠としてのみ記載できます。チケットキーは、トラッカー記録、コミットメッセージ、計画ドキュメント、引用において機能的なメタデータとして記載できますが、コードコメントやユーザー向けコンテンツには決して記載しません。
• たどれないことを事実として述べない: 引用されたパスにあるコード、固定されたコミット、テスト、ドキュメント、または一次情報源にまでたどれないことを事実として述べてはいけません。もっともらしい推測を事実として提示することは、「情報源はこれについて何も述べていない」と述べるよりも悪いことです。references/truth.md を参照してください。
• 1 つの事実には 1 つの置き場所。 それ以外はすべてオーナーへリンクします。要約は案内することはできても、決定することはできません。索引とその情報源が食い違う場合、情報源が優先され、索引がバグです。
• 承認された決定と適用済みマイグレーションは不変。 訂正は日付付きの新しいエントリであり、履歴の編集ではありません。
• 見出しは文頭大文字方式とし、タイトルケースにはしません。

ワークフロー

1. まず読む（上記）、そしてドキュメントを分類します。
2. 起草前に宣言する: 上記のチェックポイント（種類、読者、目的、非目標）を記入します。
3. 結論を先に書く: あらゆるレベルで、すなわちドキュメント、章、段落において。前置きや、結果の前に置く状況説明の段落は不要です。各章は、どのように取り組んだかではなく、そこから何が得られたかで始めます。
4. すべての主張を根拠づける そしてその確信度を示します: references/truth.md。
5. スタイルパス: 文、語句、見出し、および禁止構文リストを確認します: references/style.md。
6. 納品前に検証する: チェックリストのために reviewing-technical-prose を読み込みます。参照を実際にたどって確認します。

読者

書き始める前に、誰に向けて書くのかを把握します。「ユーザー」ではなく、実在の人物、その人が置かれた状況、その人が達成しなければならない動詞です。

読者	その人が必要とするもの
開発者	その選択の背景にある理由、そして明日から自分の仕事がどう変わるか
テックリード / アーキテクト	トレードオフ、代替案、長期的な帰結
経営層 / プロダクトオーナー	何がもたらされ、何がかかり、どのようなリスクがあるか
外部の関係者	内部のチーム名や、説明のない専門用語は使わない

複数のグループを同時に対象とする場合: 概要は最も広いグループに向けて書き、残りは深掘りしてかまいません。脚注が必要になるような表現は、脚注を付けるのではなく書き直すべきです。

よくある間違い

• 解決策から始めてしまう。まず問題、次に提案です。
• コードがすでに示していることを文書化してしまう。ドキュメントは根拠、制約、不変条件、代替案を担い、コードは「何か」を担います。
• 検証されていない主張: 数値や出典のない「より速い」「より良い」。数値を添えるか、その主張を削ります。
• 空白を、空白だと明示する代わりに、もっともらしい推測で埋めてしまう。
• 責任者の不明確さ: 名前や役割のない「これはまだ調査が必要」。
• 利点だけを列挙してしまう。あらゆる提案はそのコストを明示します。
• 編集パス中に、ホストドキュメントを黙って刈り込んだり、強調のために並べ替えたり、スタイルを変えたりしてしまう。編集は外科手術的に行います。声、構造、番号付け、ID を保ちます。
• おおよそ 800 行を超える散文のドキュメント: 分割し、メインドキュメントから各部分へリンクさせます。