【エンジニアのためのドキュメントライティング術】最低限知っておきたい、ドキュメントの重要性と書きはじめる前の準備

エンジニアのためのドキュメントライティング術 第1回

　一定の規模の開発であればドキュメントは必須です。ドキュメントを使わない開発が存在するならば、すべての情報を口頭やチャットを使い、ソースコードレベルで記述する必要があります。一方で、効果的に記述されて運用されているドキュメントには、開発組織・チームをスケールさせる力があります。ドキュメントは互いの時間を拘束せずに非同期で書いたり、読んだりできるからです。したがって、ドキュメントを効果的に使えるならば、開発組織・チームの生産性を向上できます。しかし、ドキュメントの書き方をしっかり学んでいる人は多くないです。もしドキュメントライティングの基礎技術を事前に身につけられるならば、今後の開発者人生において非常にレバレッジの効くスキルとなります。本記事では、ドキュメントライティング術を学んだことがない人向けに、「ここまでは最低限知っておくと良い」という知識をお伝えします。

対象読者

　対象読者は、以下を想定しています。

• ドキュメントライティングをしっかり学んだことがない方
• ドキュメントに課題感を持っている方

　本連載の構成は次の通りです。

• ドキュメントの重要性
• ドキュメントライティングの3フェーズ
  • フェーズ1：準備
  • フェーズ2：作成
  • フェーズ3：運用

• 生成AIとドキュメントライティング

　なお、最後のセクションでは、ドキュメントライティングに対する生成AIの考え方・活用方法についても扱います。現代の業務では、生成AIが切っても切り離せない技術となりつつあり、今後もその関係はさらに深まっていくと筆者は考えるためです。

　本記事では、上記構成のうち、「ドキュメントの重要性」と「フェーズ1：準備」までを扱います。

ドキュメントの重要性

　ドキュメントはなぜ重要なのでしょうか？ 一言で表現すれば、「チームを効果的にスケールさせるために、維持させるために必須だから」です。また、ドキュメントは「読み手のため」および「書き手（自身）のために」になります。少し具体的に説明しましょう。

効果的にスケールさせるため

　一定の規模の開発であれば、ドキュメントは必須です。もしドキュメントを使わない開発が存在するならば、すべての情報を口頭やチャットを使ったり、ソースコードレベルで記述したりする必要があります。これはコストに見合いません。

　一方で、効果的に記述され運用されているドキュメントには、開発組織・チームをスケールさせる力があります。ドキュメントはお互いの時間を拘束せずに非同期で、書いたり読んだりできるためです。

　また、ドキュメントに起こされてない知識は簡単に暗黙知となります。ある機能を開発した本人は、その機能の設計や実装を深く理解していますが、他者が背景情報を含めて理解するのは簡単ではありません。開発者同士で互いに話して、背景や内容を理解すれば、暗黙知を形式知に変えていけますが、それでも情報を残しておかなければ将来的に苦労することになります。

　使い捨てのスクリプトのようなワンショットの開発であれば、ドキュメントを起こす必要はあまりないかもしれません。しかし、それ以外の開発であれば、何らかのドキュメントを残しておいたほうがよいでしょう。そして、ワンショットのProof of Conceptのように使い捨てだと考えて作ったシステムの中には、長続きするものもあります。

読み手のため・書き手（自身）のため

　ドキュメントは読み手のために書くものが大半です。書き手の考えを読み手に伝えることによって、何らかの状態変化・行動変容を起こしたいのです。たとえば、GitHubのリポジトリに含まれるREADMEであれば、それを読むことで簡単に使い始めたり、開発に参加し始めたりすることを狙います。他にも、SaaS向けのユーザーマニュアルであれば、読み手がその内容を読むことで、そのサービスの使い方を把握している状態になることを狙います。

　しかし、ドキュメントは書き手のためにもなります。ドキュメントを書く過程で、論理のつながりを意識する必要があるため、あいまいな箇所が自然と浮かび上がってくるのです。脳内で考えているだけだと、論理性が欠けている部分や不明確な点に気づきにくくなります。それを文章にすることで、自分の思考をより客観的に見つめ直す機会が得られるのです。この過程は、ラバーダック・デバッグ（※ゴム製のアヒルなどに声に出して説明することで解決策を見つけ出すデバッグ手法）に似ているかもしれません。

　ドキュメントの重要性が理解できたところで、実際に取り組む方法について見ていきましょう。

ドキュメントライティングの3フェーズ

　本記事ではドキュメントライティングを3つのフェーズである、（1）準備、（2）作成、（3）運用に分けて考えます。フェーズの詳細に入る前に、3フェーズそれぞれの概略を紹介します。

　最初のフェーズは「準備」です。ドキュメントライティングという名前から、いきなり書き始めたくなる気持ちもわかります。しかし、書き手が思いついたままに、それをドキュメントに起こしてしまうと、プロダクト作りと同じ罠にかかってしまいます。すなわち「ある機能を作ったのに、誰も使ってくれない」ということになりかねません。ドキュメントであれば、「ドキュメントをせっかく書いたのに、誰も読んでくれない」といった事象に陥ります。プロダクト作りと同じように「読み手の」「何を解決しているか」を考えて書く必要があります。その方法の詳細は後述します。

　次のフェーズは「作成」です。実際にドキュメントを書き始めるのがこのフェーズです。ドキュメントのフォーマットを選び、骨格（見出しや段落構造）を設計してから、文章を書いていきます。この際、全体像（森）と詳細（木）の両面を抑えておくことが大切です。

　最後のフェーズが「運用」です。ドキュメントはリリースして終わりではありません。そのドキュメントが狙った通りの効果を出せているのか計測して改善する必要があります。これもまさにプロダクト作りと同様です。また、開発状況によっては廃止予定（Deprecated）となった機能（非推奨となった機能）も発生してくるでしょう。その場合は、ドキュメントも同様のプロセスで廃止していく必要があります。