📝

ドキュメント化についてのノウハウ

2025/04/08に公開

序章. ドキュメント化について

本稿は、ドキュメント化時の最適な方法を、私なりにまとめたノウハウになります。
ドキュメントを作成する時の参考になれば幸いです。

各章の概要として

本稿は、以下の章に分けて説明を記載しています。

1章. 構成
- 1.1章用語一覧: ドキュメントの初めに用語の一覧を作成する。
- 1.2章主張（頂点）の作成: ドキュメントの主張を作成する。
- 1.3章ピラミッド原則: ドキュメントを構造化するための構想（骨組み）を作成する。
- 1.4章 4つの原則: 人が覚えやすい項目数や階層数は、最大4つが適切とする。
2章. 文章
- 2.1章長さ: 一文の適切な長さについて
- 2.2章言葉づかい: 一文を読みやすくするための言葉づかいについて
- 2.3章文の構成: 視覚的に要点が理解しやすい文の構成について
3章. 図解
- 3.1章リッチピクチャ: ドキュメントの全体像を把握する
- 3.2章 UML: より詳細な情報の把握の助力となる

各章の関係性として、1章. 構成はドキュメントの骨組みを作成するためのものであり、2章. 文章はその骨組みに肉付けをするためのものです。
3章. 図解は、ドキュメントの内容を視覚的に理解しやすくするためのものです。
この3つの要素を組み合わせることで、読者にとって読みやすく効果的なドキュメント化が可能になります。また、書き手にとっても、ドキュメント化の負担を軽減することを目的としています。

1章. 構成

本章の構成では、文章を記述する前のドキュメントの骨組みに関する内容を説明します。
ドキュメントの構成をあらかじめ決めておくことで、読者に伝わりやすいドキュメントを作成できます。
本セクションは次の、用語一覧、ピラミッド原則、主張（頂点）の作成、4つの原則に分けて説明します。

1.1章. 用語一覧

ドキュメントの初めに、ドキュメントで使用する用語一覧を作成する。
用語一覧を作成することで、ドキュメントの複雑な内容の理解の助けとなります。
また、用語一覧を作成によって、次の効果が得られます。

用語の表記揺れの防止 :
- 例として、ModuleやObjectなど、意味が同じになりがちな用語を説明することで、表記揺れを防ぎます。
説明の簡略化 :
- 用語一覧によって、以後の内容に現れる用語を既知情報として扱うことで、各章の内容理解を軽減できる。

例: 用語一覧の例 :

用語	意味
API	アプリケーションプログラムインターフェイス。ソフトウェア間の通信手段。
モジュール	プログラムの機能を分割した単位。
オブジェクト	プログラム内でデータとその操作をまとめたもの。

上記のように、作成した用語一覧はドキュメントの初めに記載すると効果的です。
ドキュメントの初めに用語一覧があることで、読者は用語を既知の情報として扱うことができ、内容に集中できます。

1.2章. 主張（頂点）の作成

ドキュメントを作成する前に、主張（頂点）を作成することでドキュメント全体の方向性を決定します。
主張（頂点）を作成するための手法として、OPQ分析を用いることで効率的に明確な主張を作成できます。

1.2.1章. OPQ分析

OPQ分析は、以下の3つの要素から成り立っています。

O (Objective: 望ましい状況): ドキュメントの目的や目指すべき状態を明確にします。
P (Problem: 問題): 現在の状況や問題点を明確にします。
Q (Question: 読み手の疑問): 読者が持つ疑問や興味を明確にします。

この3つの要素を明確にすることで、ドキュメントの主張（頂点）を作成します。
下記の例は、万有引力を題材にしたOPQ分析の例です。

例：万有引力の法則を題材にしたOPQ分析の例
- O (Objective: 望ましい状況)
  - すべての物体が互いに引き合う力を持つという万有引力の法則を正確に理解し、応用できる状態。
- P (Problem: 問題)
  - 万有引力の法則が正しく理解されていないため、潮の満ち引きや惑星の運動などの現象を説明できない。
- Q (Question: 読み手の疑問)
  - 万有引力の法則とは何か？
- 以上のOPQ分析から、主張（頂点）は万有引力の法則の手引きといったように作成します。

上記のように、OPQ分析を用いて、ドキュメントの主張（頂点）を作成することで、ドキュメント全体の方向性を決めることができます。
主張（頂点）を明確後は、ドキュメントの内容を具体化します。

1.3章. ピラミッド原則

主張（頂点）を作成した後は、ピラミッド原則を用いてドキュメントの内容を具体化します。
ピラミッド原則を用いることで下記のような効果が得られます。

ピラミッド原則を用いると、主張（頂点）から詳細まで矛盾なく整合性の取れた文書構成を作成できます。
詳細な情報を後に示すことで、読者は必要な情報を段階的に理解できます。
書き手にリバースアウトライン^[1]を促し、主張（頂点）から詳細にかけての全体像を把握しながら、記述を進めることができます。
また、読者目線と同じ流れで、情報を主張から詳細にかけて記述することでより理解しやすいドキュメントを作成できます。

1.3.1章. ピラミッド原則を用いた構成の作成

ピラミッド原則による構成は、以下のように作成します。

主張（頂点）: ドキュメントの主張を記載します。
主要なサポートポイント: 主張を支える主要なポイントを記載します。
詳細な説明: 主要なサポートポイントに対する詳細な説明を記載します。
具体的な情報: 詳細な説明に対する具体的な情報を記載します。

ピラミッド原則では、主張（頂点）に対して、下位階層にその説明や理由を述べます。

さらに、その下位階層では、より具体的な説明や理由を追加します。
このように、主張（頂点）から具体的な内容へと階層化し、ピラミッド型に構成するのがピラミッド原則です。
ピラミッド型を作成する際のポイントとして、1つ1つの要素は簡易的な見出しで大丈夫です。
詳細な説明はピラミッド型を作成した後に記載するといった流れになります。
例として、万有引力を題材に、実際にピラミッド原則を用いたピラミッド原則は以下のようになります。

例：万有引力の法則を題材にしたピラミッド原則の例

万有引力の法則 (主張（頂点）): すべての物体は互いに引き合う力を持つ。

地球と月の引力 (主要なサポートポイント): 地球と月の間の引力が潮の満ち引きや月の軌道運動を引き起こす。

物体が落下する理由 (主要なサポートポイント): 地球の重力が物体を引き寄せるため、重力加速度や自由落下運動が観察される。

以上のように、ピラミッド原則を用いることで、ドキュメントの主張から詳細な情報までを階層化し、整合性のあるドキュメント構成を作成できます。
ただ、ピラミッド化することで、情報が階層的に整理されていることが理想ですが、作成した内容に矛盾が生じてしまう場合があります。
その場合は、つなぎ言葉を用いることで、矛盾を防ぐことができます。
次の章では、つなぎ言葉について説明します。

1.3.2章. つなぎ言葉

ピラミッド原則用いたピラミッド型を作成するときに、説明や理由、結果の主張が同じ階層で、矛盾してしまう場合があります。
矛盾を防ぐ方法として、つなぎ言葉を用いることで、ピラミッド化時の矛盾を防ぐことができます。
同じ階層の内容に対してつなぎ言葉追加し、上位と下位の説明や理由の整合性を保つことができます。
例として、万有引力を題材にしたつなぎ言葉の例を以下に示します。

例：万有引力の法則を題材にしたつなぎ言葉の例

第一階層の万有引力の法則は、第二階層の地球と月の引力と物体が落下する理由を導く事柄として説明しています。

その際のつなぎ言葉は、法則を導く事柄としてです。

第二階層の地球と月の引力は、第三階層の潮の満ち引きと月の軌道運動を説明する事柄として説明しています。

その際のつなぎ言葉は、引力の説明としてとなります。

ポイントとしては、同じ階層の内容に対してつなぎ言葉は同じ内容になることです。
同じ内容のつなぎ言葉を追加し、上位と下位の説明や理由に違和感を感じたら、ピラミッド型の構成を見直してください。
「違和感がある見出しを修正し、再度構成を確認」を繰り返すことで、上位と下位の説明や理由の整合性が高いドキュメント構成を作成できます。
このように、つなぎ言葉を用いることで、ピラミッド型の構成に対する矛盾を防ぐことができます。
次に、ピラミッドを作成する際の注意点として、ピラミッド型の構成が大きくなると、情報過多になりドキュメントの内容が理解しにくくなる場合があります。
その場合は、4つの原則を用いることで、情報を整理し読者の理解しやすいドキュメントを作成できます。

1.4章. 4つの原則

4つの原則は、マジックナンバー4^[2]に基づく、ドキュメント化の原則^[3]です。
ドキュメント内のあらゆる要素に対して、最大4つまでを適用することで、書き手にも読み手にも理解しやすい範囲の情報を示すことができるという考え方になります。
理解しやすい範囲とは、人間の認知や記憶のしやすさを考慮したものです。

4つの原則を用いて、ように定義すると良いと思います。

4つの項目
- 例: 目的、方法、結果、考察
4つの階層
- 例: 主張、主要なサポートポイント、詳細な説明、具体的な情報
4つの要素
- 例: 文章、図解、表、グラフ

4つの原則に従うことで、ドキュメントはより認知しやすくなります。
書き手にとっては、記述する要素を4つに制限することで、ドキュメントの構成が単純になり記述しやすくなります。
読者にとっては、要素を4つに制限すること、理解の負担は軽減され、ドキュメントの内容を把握しやすくなります。また、要点を絞ることで、重要な情報を見逃しにくくなります。

2章. 文章化

次は、説明や理由の文章化についての説明します。
文章化は、長さ、言葉づかい、文の構成の3つを考慮することで、より読みやすい文章を作成する方法を説明します。
各要素は、ドキュメントの内容を明確にし、読者に伝わりやすくするための重要な要素です。
それぞれの効果として、以下のような効果があります。

長さ: 文章の長さは、1文の読みやすさに影響を与えます。
言葉づかい: 言葉づかいは、文章の印象を決定します。
文の構成: 文の構成は、文章の理解を助けます。

各章の適応範囲について
適応範囲としては、長さ、言葉づかいは一文に対するものであり、文の構成は文章または、段落に対するものになります。

2.1章. 長さ

文章の長さは、一文の読みやすさに大きく影響します。
短すぎず長すぎず、適切な長さの一文を保つことで、読みやすい文章を作成できます。
また、一文に含む情報量を適切に調整することも重要です。
一文に含まれる情報量が多すぎると、読者は内容を理解しにくくなります。
以下の点に注意することで、文章の長さを適切に保てます。

一文の長さは80文字程度が適切です。
一文一義とは、1つの文に1つの意味を持たせることです。
また、句読点は1文に最大2つを心がけることで、文章が読みやすくなります。
例：多くの情報を持つ80文字以上の一文（複雑な文章の例）
- 「日本の大学生の勉強時間に関する調査によると、94.3％の学生が『1日あたり2、3時間』と答えているが、その原因は不明で、この勉強時間は諸外国平均6時間より少なく、アメリカ平均8時間とも差がある。」
例：80文字以内で一文一義の文章の例（適正例）
1. 日本の大学生の勉強時間に関する調査によると、94.3％の学生が「1日あたり2、3時間」と答えています。
2. この勉強時間は諸外国平均6時間より少ないです。
3. アメリカ平均8時間とも大きな差があります。
4. 勉強時間が少ない原因は不明です

2.2章. 言葉づかい

言葉づかいは、文章の印象を決定します。
ただ、言葉遣いに気を遣うところが多すぎると、文章の作成が難しくなります。
そのため、言葉づかいは、以下の2つの観点を考慮しています。

主語を明確にする: 主語を明確にすることで、文章の意味が伝わりやすくなります。
代名詞は避ける: 代名詞を避けることで、文章の意味が明確になります。
例: 主語を明確にする:
- 修正前：「アインシュタインは多くの理論を発表した」
- 修正後：「アインシュタインは特殊相対性理論や一般相対性理論を発表した」
例: 代名詞を避ける:
- 修正前：「彼は相対性理論を発表しました。それは物理学に革命をもたらしました。」
- 修正後：「アインシュタインは相対性理論を発表しました。相対性理論は物理学に革命をもたらしました。」

2.2.1章. 校正ツール

VS Codeでドキュメントを作成する際に役立つ、文章の誤りを自動的に検出してくれる校正ツールを紹介します。
オススメは、テキスト校正くんというVS Codeの拡張機能です。
テキスト校正くん
テキスト校正くんは、以下の機能を提供しています。

文法チェック
リアルタイムチェック
固有名詞のチェック
助詞の連続など基本的な文法チェック

テキスト校正くんのような校正ツールを使用することで、文章の誤りを自動的に検出できるため、校正作業の負担を軽減できます。
ただし、校正ツールはあくまで補助的なものであり、最終的な校正は自分自身で行う必要があります。

2.3章. 文の構成

文の構成は、文章を読者に効果的に伝えるための重要な要素です。
文の構成を考慮することで、文章の意味が明確になり、読者に書き手の意図が伝わりやすくなります。
文の構成について、以下の2つの観点から説明します。

W5H1
- W5H1を考慮することで、読者に何を伝えるべきかを明確にできます。
  - W5H1の順序
    - この順序は複数のパターンで説明します。
    - それぞれのパターンは、伝えたい内容や目的に応じて使い分けることができます。
    - 適切な順序を用いることで、情報の優先順位を整理し伝えたい内容を効果的に伝達できます。
視覚的な要点の強調
- 視覚的な要点の強調は、文章を構成する際に要点を視覚的に際立たせる手法です。
- これにより、読者の理解を助け、重要な情報を見逃しにくくします。

この2つの観点を活用することで、より効果的で分かりやすい文章を作成できます。

2.3.1章. W5H1

W5H1は、文章を構成するための要素を指します。
以下の6つの要素で構成されています。

Who: 誰が
- 担当者、責任者、関係者など。誰が関与しているかを明確にすることで役割分担がしやすい
What: 何を
- 商品、サービス、業務内容など。具体的なタスクや目標を明示する
When: いつ
- 時期、日付、時間帯など。情報伝達において「いつ」が明確でないと行動が適切に進められない
Where: どこで
- 会場、建物、地域など。物理的な場所だけでなく仮想空間も含む
Why: なぜ
- 行動や決定の理由や目的。背景や原因を共有することで理解が深まり、問題解決が容易になる
How: どのように
- 方法やプロセス。具体的な手順を示すことで効率性や一貫性が向上する

この、W5H1の要素の順序を考慮することで、伝える方の内容や目的を選ぶことができます。

2.3.1.2章. W5H1の順序

下記は、W5H1の順序をプレゼン、問題解決、緊急対応の3つのシーンに分けて説明します。

プレゼンの場合:優先順位: Why > What > How > Who = When = Where
- ※Who、When、Whereは同じ優先順位です。
大勢の人に向けて説明する場合は、Whyを最初に持ってくることで、聴衆と同じ疑問を共有することできます。
その後、Whatを説明することで、聴衆は問題を理解しやすくなります。
次にHowを説明することで、聴衆は問題の解決策を理解しやすくなります。

問題提起の場合:優先順位: What > Why > How > Who > When > Where
問題解決のために、Whatを最初に持ってくることで、問題を明確にします。
その後、WhyからHowを説明することで、問題の原因と解決策を提示します。
このように最初に問題点から説明することで、読者は問題を理解しやすくなります。

緊急対応の場合:優先順位: What → How → Who → When → Where → Why
緊急対応の場合は、Whatを最初に持ってくることで、問題の発生を明確にします。
その後、Howを説明することで、問題の詳細を理解しやすくなります。
このように問題を詳細に説明することで、より具体性のある情報を提供できます。

2.3.2章. 視覚的な要点の強調

文章を構成する際に、視覚的に要点を強調することで、読者の理解を助けます。
WordやExcelなどのオフィス系ソフトウェアでは、フォントサイズ、太字や下線、色を用いて視覚的に要点を強調できますが、ここでは、Markdownでドキュメントを記述することをオススメします。

2.3.2.1章. Markdownについて

Markdownは、テキストを装飾するための軽量マークアップ言語です。
イメージとしては下記のような流れで、MarkdownをHTMLに変換し、ブラウザで表示します。

下記の画像は、Markdownで記述したドキュメントをHTMLに変換し、ブラウザで表示したものです。
右側が、Markdownで記述したドキュメント、左側がHTMLに変換したものになります。

webアプリケーションのStackEditでMarkdownを記述できます。https://stackedit.io/

Markdownでの記述をオススメする理由としては、以下のような理由があります。

テキストに直接構文を記述することで、視覚的に要点を強調できる。
- Markdownはテキストを装飾するための軽量マークアップ言語です。
- テキストに、直接構文を記述することで、視覚的に要点を強調できます。
さまざまなWebサービスでMarkdownで記述できる。
- 例:Zenn、GitHub、Qiita、など
エディターでもMarkdownで記述ができる。
- 例:VS Code、Typora、など
AIモデルへのプロンプトでもMarkdownで記述できる。
- 例:ChatGPT、Bard、など

Markdownの記述については、下記を参考にしてください

3章. 図解

図解は、文章を補完するための重要な要素です。
図解には、リッチピクチャとUMLの2つの方法があります。
図解を用いることで、文章の内容を視覚的に理解しやすくなります。

3.1章. リッチピクチャ

リッチピクチャは、物事の関係を視覚的に表現し全体像を把握するための図解化の手法です。
図解化するためのツールとしては、Draw.ioをオススメします。Draw.io
Draw.ioを使用することで、簡易的にリッチピクチャを作成できます。

例として、以下は映画「ロック、ストック＆トゥー・スモーキング・バレルズ」の関係図になります。

上記のように、関係する人物や物事を視覚的に表現することで、全体像を把握しやすくなります。

3.2章. UML

UMLは、Unified Modeling Languageの略で、ソフトウェア開発におけるモデリング言語です。

UMLは、以下のような図を使用して、システムの構造や振る舞いを視覚的に表現します。
- クラス図
  - クラスの属性やメソッドを表現する図
- シーケンス図
  - オブジェクト間のメッセージのやり取りを表現する図
- コンポーネント図
  - システムの構成要素を表現する図
- アクティビティ図
  - システムの処理の流れを表現する図
- ほかにも、状態遷移図やユースケース図など、さまざまな図があります。

mermaid.jsを使用することで、UMLの図を簡単に作成できます。
手軽に図解を作成できるため、ドキュメント化においても広く使用されています。

mermaid.jsの公式サイト mermaid.js
mermaid.jsは、Markdownに埋め込むことができるJavaScriptライブラリです。
mermaid.jsを使用することで、UMLの図を簡単に作成できます。
VS Codeの拡張機能でMarkdown Preview Mermaid Supportを使用することで、VS Code上でUMLの図を作成できます。
リンク: Markdown Preview Enhanced
クラス図のサンプル

クラス図のMarkdown記法

````mermaid
classDiagram
    class Person {
        +String name
        +int age
        +void greet()
    }
    class Student {
        +String studentId
        +void study()
    }
    Person <|-- Student
```

シーケンス図のサンプル

シーケンス図のMarkdown記法

```mermaid
sequenceDiagram
    participant User
    participant System

    User->>System: Request data
    System-->>User: Return data
```

アクティビティ図のサンプル

アクティブ図のMarkdown記法

```mermaid
graph TD
    A[Start] --> B[Process 1]
    B --> C{Decision}
    C -->|Yes| D[Process 2]
    C -->|No| E[Process 3]
    D --> F[End]
    E --> F
```

コンポーネント図のサンプル

コンポーネント図のMarkdown記法

```mermaid
graph TD
    A[Component A] --> B[Component B]
    A --> C[Component C]
    B --> D[Component D]
    C --> D
```

上記のように、mermaid.jsを使用することで、UMLの図を簡単に作成できます。

以上、ドキュメント化のノウハウをまとめました。

参考資料

OPQ分析や、ピラミッド化、つなぎ言葉についての参考になった書籍になります。
入門考える技術・書く技術――日本人のロジカルシンキング実践法

脚注

リバースアウトライン: ドキュメントの各章の要点だけ抜き取り、全体像を把握する方法。 ↩︎
マジックナンバー4：人間の短期記憶が一度に保持・処理できる情報単位の限界を指します。従来「マジックナンバー7±2」が有名でしたが、近年の研究ではこの限界が「4±1」に修正されています。これは、注意の焦点が一度に処理できる対象が約4つであることを示し、人間の情報処理能力の基本的特性を示唆しています。マジックナンバー7±2（英文） ↩︎
そういった原則があるわけではなく、私が勝手に原則と言っています。 ↩︎

GitHubで編集を提案