はじめに
流通事業部の内堀です。
フューチャー社内の有志メンバーでテクニカルライティングガイドラインを作成し公開しました！
設計書、Pull Requestの説明、Slackでの相談、障害の一次報告。ITコンサルタントの仕事は、文章を書くことと切り離せません。本ガイドラインが対象にするのは、こうした日々の文章そのものです。専門的な概念を構造化し、判断に足る情報を示して意思決定を推進するための技術をまとめました。
本記事では、ガイドライン作成の背景と全体像、そして内容の一部を抜粋して紹介します。
なぜテクニカルライティングをガイドライン化したのか
本ガイドラインは、これまで個人のセンス頼みだった「説明力」を、誰でも参照できる形式知へと落とし込むために作成しました。
こんな場面に心当たりはないでしょうか。
- 丁寧な状況共有をもらったが、結局自分が何をすればいいのか分からず「で、何をしてほしいの？」と聞き返した
- レビュー依頼を受けたものの、どこをどのレベルで見ればいいのか判断できず、着手を後回しにしてしまった
- Pull Requestの説明が「実装しました」「テストコードを追加しました」の羅列で、なぜその変更が必要なのかが読み取れない
どれも、書き手に悪意や手抜きがあるわけではありません。単に「こう書けば伝わる」という型を持っていないだけです。
コードにはコーディング規約があり、設計には設計ガイドラインがあります。一方で、私たちが業務時間の中で最も多く生産しているアウトプットである文章には、これまで拠り所となる基準がありませんでした。「分かりにくい」という指摘が指摘する側の感覚に依存し、指摘される側は何を直せばいいのか分からない。この状態を解消したいというのが、本ガイドラインの出発点です。
ガイドラインの全体像
本ガイドラインは、文章を書く一連の流れに沿った5つのフェーズで構成されています。
| フェーズ | 扱う内容 | 主なキーワード |
|---|---|---|
| 設計（Design） | 書き出す前に、メッセージと文脈を定義する。読み手の期待値を整理し、ブレない軸を作る | 5W1H / 空・雨・傘 |
| 執筆（Write） | 具体的な書き方の作法。構造化・簡潔さ・正確性を追求し、読み手の認知負荷を下げる | PREP / STAR / 構造化 |
| 実践応用（Apply） | 実務の典型場面で使えるパターン集。設計書、トラブル報告、依頼などの「型」を習得する | トレードオフ / ADR / 依頼作法 |
| 品質向上（Improve） | 書いた後の磨き込み。セルフレビューと適切なレビュー依頼により、品質の最終調整を行う | セルフレビュー / 差し戻し防止 |
| 育成（Nurture） | 他者の文章を育てる技術。チーム全体の文章力を底上げするための指導法を扱う | フィードバック技術 / 指導法 |
前半の「設計」「執筆」は個人の書く力、後半の「品質向上」「育成」はチームの書く力に軸足を置いています。通読する必要はなく、気になるフェーズから拾い読みできる構成にしています。
ピックアップトピック
ボリュームがあるため、ここでは特に汎用性の高い3つのトピックを抜粋して紹介します。
事実だけでなく見解まで述べる（空・雨・傘）
空・雨・傘は、メッセージを設計する際の論理展開の基本となるフレームワークです。
- 空（事実）: 空に黒い雲が出ている（客観的な状況、調査結果）
- 雨（解釈）: 雨が降りそうだ（事実に基づく分析や課題の特定）
- 傘（見解）: 傘を持っていこう（取るべきアクションの提案）
実務の報告では、空と雨だけで止まってしまうケースが多くあります。ガイドラインでは、次のような報告を典型例として挙げています。
〇〇について調査したところ、▲▲に課題がありました
この報告だけでは、読み手は「つまり、自分は何をすればいいの？」をゼロから考えなければなりません。相手が知りたいのは「あなたがどうしたいのか」あるいは「私は何をすればよいのか」という傘の部分です。
事実をただ羅列するのではなく、そこから何をするべきかを示すことで、仕事を前に進めることができます。
結論から述べる
一生懸命いろいろと書いてくれているのに、結局何が言いたいのか分からない。誰もが一度は受け取ったことのある文章ではないでしょうか。
Yes/Noを問われているのに周辺情報から書き始めると、結局どちらなのかの判断は読み手任せになります。ガイドラインでは「ゲストユーザーでも資料はダウンロードできますか？」という問いへの回答を例に挙げています。
❌ NG
ダウンロードボタンの権限を確認したところ、現在は会員のロールのみ許可フラグが立っています。
このため、ゲストユーザーですと、ボタンが非表示になるため、ダウンロードはできません。
✅ OK
ゲストユーザーはダウンロードできません。
現状の仕様では権限が正社員に限定しているためです。
内容は同じですが、後者は1文目で問いに答えています。調査の過程を前に置かず結果から返すことで、読み手は最短時間で次のアクションに移れます。
答えが出ていない場合も同じです。「いつまでに〇〇ボタンの仕様は確定しますか？」と聞かれた場面を考えます。
❌ NG
現在、〇〇チームに確認をしているところで、まだ返事がきていないです。
後ほどリマインドを入れておきます。
✅ OK
現時点では未定です。
本日17時の進捗会議後に改めて回答します。
NG例では、状況の説明に終始してしまっており、質問者が一番知りたい「いつまでか」に答えられていません。未定であることも回答のひとつです。問われた要素に直接答えることで、認識のズレのないやりとりができます。
5W1Hで解像度を上げる
依頼や相談は、書き手の想像以上に、読み手にとって必要な情報が抜けがちです。情報の非対称性によるコミュニケーションミスを防ぐために、5W1Hをチェックリストとして使います。ここで重要なのは、書き手ではなく相手の立場に立って考えることです。ガイドラインでは、次のような依頼を典型例として挙げています。
AとBどちらが良いですか？
IAMロールを追加してよいですか？
こういった質問だけでは、読み手は判断できません。影響度・リスク・作業時間・代替案など、意思決定を下すために必要な比較材料を提示する責任は、書き手にあります。
あわせて確認したいのが、読み手にどのようなアクションを取ってほしいかです。単なる状況の共有なのか、A案かB案かの選択なのか、作業の承認なのか。ここが曖昧だと、傘が抜けているのと同じで、読み手に負担をかけてしまいます。
期限も同様です。都合の良い期限と、それを超過すると業務影響が出る最遅の期限の両方を伝えると、読み手に優先度を考える余地が生まれます。
同じ発想はレビュー依頼にも当てはまります。「どこを、どのレベルで見てほしいのか」を伝えることで、レビュー内容のミスマッチを防ぎ、リードタイムを短縮できます。
レベル別の読みどころ
ジュニアからシニアまで、それぞれの立場で明日から使えるトピックがあります。どこから読むか迷ったら、次の表を参考にしてください。
| レベル | まず読むセクション | 期待される効果 |
|---|---|---|
| ジュニア | メッセージ設計 / 導入の作法 | 自分の文章の「どこに課題があるか」を言語化できるようになる |
| ミドル | パターン（トレードオフを書く）/ 要件レベル（Must・Should） | OJTで若手に指摘するポイントが体系化され、「なぜダメか」の根拠を説明しやすくなる |
| シニア | フィードバック技術 / 骨組み（見出し）を作らせる指導 | チーム内の若手指導において、ガイドラインが「共通言語」として機能する |
特にシニア向けの「フィードバック技術」は、本ガイドラインの特徴的な章です。書く側の作法だけでなく、レビューする側の作法にも踏み込みました。
おわりに
ライティングはセンスではなく、型を知って繰り返し練習すれば誰でも上達できる再現可能なスキルだと考えています。全部を通読する必要はありません。まずは気になるところ、今すぐ使えそうな場所から開いてみてください。
ガイドラインは公開してからが本番なので、実務で使ってみた感想やフィードバックをいただけると嬉しいです。
- テクニカルライティングガイドライン: https://future-architect.github.io/arch-guidelines/documents/forTechnicalWriting/technical_writing_guidelines.html
- GitHub: future-architect/arch-guidelines
最後に、議論・執筆にご協力いただいた有志メンバーの皆さんに感謝します。