テクニカルライティング
技術的な情報を正確かつ分かりやすく伝えるための文書作成スキル
ドキュメントチーム
テクニカルライティングとは
テクニカルライティングは、技術的な情報を正確かつ分かりやすく伝えるための文書作成スキルである。API ドキュメント、README、ADR、障害報告書、ブログ記事など、開発者が書くあらゆる文書に適用される。
原則
読者の知識レベルに合わせて書き、結論を先に示す (PREP 法)。一文一義を守り、抽象的な表現を避けて具体的に書く。受動態より能動態の方が明確だ。
良い例 vs 悪い例
❌ 「設定が適切に行われていない場合、問題が発生する可能性があります」
✅ 「DATABASE_URL が未設定の場合、Lambda がタイムアウトします」
❌ 「いくつかの方法があります」
✅ 「3 つの方法があります: A, B, C」
❌ 「データベースが更新されます」(受動態)
✅ 「Lambda がデータベースを更新します」(能動態)
エラーメッセージの書き方
❌ Error: Something went wrong
✅ Error: Failed to connect to DynamoDB table 'users'.
Cause: Missing IAM permission 'dynamodb:GetItem'.
Fix: Add DynamoDBCrudPolicy to the Lambda function.
ドキュメントの種類
| 種類 | 対象読者 | 例 |
|---|---|---|
| チュートリアル | 初心者 | Getting Started |
| ハウツー | 経験者 | 特定タスクの手順 |
| リファレンス | 全員 | API ドキュメント |
| 解説 | 全員 | アーキテクチャの背景 |
全体像を把握するには関連書籍も有用。