はじめての領域におけるドキュメントの作り方

作ったことのない計画書、レポート、報告書など。経験・知見がない分野のドキュメント作りは大変です。

特殊事情がない限り、ここで紹介するステップで進めると、大体なんとかなります。重要なのはドキュメント作成のアプローチです。

７つのステップ

基本は「仮説検証」アプローチ。「集めた情報」をもとに「仮説」でドキュメントを作り、最終成果物ベースで「レビュー」をしてもらって完成に持っていきます。

多くの人が、これを見ると「面倒」「大変」「そこまでしなくても」という印象を持ち自分のやり方に最終的に固執します。だからうまくいかないのです。

❶ドキュメントの目的（完成基準）を定義する
❷関連するインプット資料・情報を集める
❸不明点・疑問点の調査
❹目次・構成のドラフト（たたき）をつくる
❺有識者レビュー
❻ドキュメントのドラフト（たたき）をつくる
❼最終レビュー

多くの人が「なぜ作るのか？」を定義せず、「なんとなくこんな感じ」で作っていることが多い。目的は？読み手は？読み手のレベルは？作ったドキュメントでやりたいことは？これらをしっかりと定義することが、ドキュメント品質に大きく関わります。

同じ障害報告でも、読み手が社内・社外で変わります。役員向けなのか、チーム内なのか、エンジニア向けなのか、ユーザー向けなのか。単なる報告資料なのか、責任をなすりつけるための資料なのか。その資料は配布で終わるのか、意思決定に使われるのか。目的は全然変わります。

関連する資料・情報を集めまくります。なにを集めるのか？この集めるときの手掛かりとなるのが❶の目的です。

この過程で、そのまま使える資料が見つかることもあります。ここで集めた資料・情報が作成するドキュメントの根拠となります。

お客様への障害報告会であれば、報告会の出席者情報は必須。提案書やプロジェクト関連の計画書系であれば、会社のフォルダをあさると、過去の資料で案外良いものが見つかります。

こういった資料・情報を集めずに、頭の中だけで考えて作成したドキュメントは、根拠に乏しく「それはあなたの感想」的なものになり、大体が総ツッコミにあいます。自己満足資料。

インプット資料・情報を集めて読み込み、理解を進めていくと、不明点・疑問点が出てきます。隠れた前提や、一部の人たちだけに当時使われいた用語、ドキュメントの矛盾点など。これらを知ってそうな人に聞く。

資料や情報を理解せずいきなり聞きにいくと、大体嫌がられますので注意。結構、多くの人がやりがち。相手も忙しいです。よっぽどの緊急な場合を除き、自分の理解を深めた上で、聞きにいくのが鉄則です。

慣れてくると、この段階でなんとなくの難易度や方向性・ドキュメントの温度感・雰囲気が肌感わかってきます。

目次・構成をつくります。重要なのは、中身はこの時点では書きません。繰り返しですが、「目次・構成」です。ここが一番の肝。全体の流れ、順番、網羅性、粒度などを考慮します。もっともあたまを働かせるところであり、考えるところ。そして、一番難しい。

目次・構成がしっかりしていると、この後の手順❻以降は文章を作成する「作業」になります。多くの人が、「作業」から着手して、仕事をやった気になっていること多いです。そして、目次レベルで手直し、手戻りが一番効率悪い。

目次・構成が重要なので、できれば有識者（知っている人・詳しい人）のレビューを受けたい。ドキュメントを発表する人がいればその人。誰もいなければしょうがないですが、できるだけ第三者の目で見てもらうのが良い。

レビューしてコメントをもらうことを嫌がる人がいますが、作成するドキュメントの品質を良くするためのコツです。どうせ何か言われます。であるならば、早い方がよい。

多くの人が、この文章を作るところからスタートします。でも、間違い。

ドキュメントを作るのは、情報があつまって目次・構成が整理された後。そして、もうこの段階は作業。作業は手足を動かすし、なんとなく形ができる。なので仕事やった感を感じるのですが、違います。作業です。

できたものを最終レビューしてもらいましょう。これで良さそうであれば完成。
お疲れ様でした。

だいたい以下のことをやると失敗します。