| name | technical-writing |
| description | 技術文書の品質を向上させます。README、コードコメント、API文書、設計書、
ユーザーガイド、サンプルコードの執筆時に使用します。
Google Technical Writingコースに基づくベストプラクティスを適用します。
|
テクニカルライティングガイド
技術文書を執筆する際の基本原則です。
クイックリファレンス
単語の選択
- 新しい用語は最初に定義する
- 同じ概念に複数の名称を使わない
- 略語は初出時に完全名称を記載: Protocol Buffers (protobufs)
- 代名詞は参照する名詞から5語以内に配置
能動態の使用
受動態: A wrapper is generated by the process.
能動態: The process generates a wrapper.
能動態は読者の処理時間を短縮し、行為者を明確にする。
明確な文章
| 避ける | 使う |
|---|
| The error occurs when... | Dividing by zero raises the error. |
| There is a variable X | The X variable stores... |
| screamingly fast | 225% faster |
短い文章
- 1文1アイデア
- 長い文はリストに変換
- 冗長表現を削減: "in order to" -> "to"
リストと表
- 箇条書き: 順序不問の項目
- 番号付き: 順序重要な手順（命令形で開始）
- 導入文を付ける: "The following steps describe..."
段落
- 冒頭文で中心テーマを示す
- 1段落1トピック
- 3-5文が理想的
読者を意識
良いドキュメント = 読者が必要な知識 - 読者の現在の知識
- 役割、知識レベル、学習目標を定義
- イディオムやローカル参照を避ける
セルフエディティング
- スタイルガイドを採用し一貫性を確保
- 読者視点でドラフトを読み直す
- 声に出して読み、不自然な表現を特定
- 時間を置いて新鮮な目で再検討
サンプルコード
- 正確: エラーなくビルド、本番品質
- 簡潔: 学習に必要な部分のみ
- 理解しやすい: 説明的な命名、ネスト最小化
- 段階的: Hello Worldから複雑な例へ
イラストレーション
- キャプションを図の作成前に書く
- 1つの図に1段落分の情報まで
- 視覚的手がかり（矢印、ハイライト）で注意を導く
アクセシビリティ
- すべての画像に適切なalt textを付ける
- 色だけで情報を伝えない（ラベル、形状を併用）
- 見出し階層を正しく使用（h1 -> h2 -> h3）
- リンクテキストは情報的に（"click here"を避ける）
- インクルーシブな言語を使用（"victim of" -> "experiencing"）
エラーメッセージ
- 原因を具体的に説明する
- 無効な入力値と期待値の両方を示す
- 修正方法を明記する
- ユーザーを責めない、ポジティブなトーンで
大規模ドキュメント
- スコープを明示（何をカバーし、何をカバーしないか）
- 対象読者と前提知識を特定
- アウトラインを先に作成
- 単純から複雑へ段階的に進行
LLM活用
- 出力は必ず検証（事実確認、コード実行）
- 機密情報をプロンプトに含めない
- 曖昧なプロンプトは曖昧な出力を生む
- 生成コンテンツは編集・カスタマイズする
詳細ガイド
基礎（Technical Writing One）
応用（Technical Writing Two）
アクセシビリティ（Accessibility）
エラーメッセージ（Error Messages）
チェックリスト
技術文書を書く際の確認項目:
