テクニカルライティング

テクニカルライティングとは

テクニカルライティングは、技術的な情報を正確かつ分かりやすく伝えるための文書作成スキルである。API ドキュメント、README、ADR、障害報告書、ブログ記事など、開発者が書くあらゆる文書に適用される。

原則

書く前に決めるべきものは文体ではなく読者だ。想定読者が既に知っていること (前提にしてよい語彙) と知らないこと (説明が必要な語彙) を線引きしないまま書くと、初心者には言葉が通じず、経験者には冗長という失敗が同じ文書の中で同時に起きる。

構成は結論から入る。結論 / 理由 / 具体例 / 結論の順に並べる PREP 法はその型のひとつで、狙いは読み手が最初の数行で「これは自分に必要な文書か」を判断できるようにすることだ。

一文一義を守る。ひとつの文に条件と結果と例外を詰め込むと、読み手は文を読み返して構造を解析する作業を強いられる。受動態を能動態へ直すのが効くのも同じ理由で、「更新されます」では誰が更新するのかが文から落ちるが、能動態なら動作主が必ず文中に現れる。

良い例 vs 悪い例

同じ内容でも、書き方によって読み手が次に取れる行動が変わる。悪い例に共通するのは、読んだ人が自分で調べ直さないと動けないという点だ。

❌ 「設定が適切に行われていない場合、問題が発生する可能性があります」
✅ 「DATABASE_URL が未設定の場合、Lambda がタイムアウトします」

❌ 「いくつかの方法があります」
✅ 「3 つの方法があります: A, B, C」

❌ 「データベースが更新されます」(受動態)
✅ 「Lambda がデータベースを更新します」(能動態)

エラーメッセージの書き方

エラーメッセージは、開発者が書く文章のうち最も切迫した状況で読まれる。何が失敗したか、原因は何か、どう直すかの 3 点が揃っていれば読み手はその場で復旧できるが、どれかが欠けるとログを漁る作業が始まる。

❌ 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.

ドキュメントの種類

種類を分けずに書き始めると、手順の途中に設計の背景が挟まり、リファレンスに入門の説明が混ざる。Daniele Procida がまとめた Diátaxis という枠組みは、この分け方を読者の熟練度ではなく状況で切る。読者が学習中なのか仕事中なのか、手を動かしたいのか理解したいのかという 2 つの軸で、4 つの形に対応させたものだ。

この分類が実務で効くのは、書く前に「これはどれか」を決めると、混ぜてはいけないものが自動的に分かるからだ。チュートリアルに設定項目の一覧を足したくなったら、それはリファレンスへ移す合図であり、ハウツーの手順書に「なぜこの設計なのか」を書きたくなったら解説へ切り出す。

文章の良し悪しは書き手の感覚では判定できない。書いた手順を自分以外の人にそのまま実行させ、詰まった箇所を直すのが最も確実だ。読み手が迷った場所は、その人の理解力の問題ではなく文書の欠陥として記録しておく。