TL;DR

ドキュメンテーションは、なるべく1つのドキュメントに多くの情報をまとめるべき
なるべく2階層以内までにまとめておくべき
それ以上の階層だとメンテナンスされづらくなり、ドキュメントの信頼性が落ち読まれなくなる

ドキュメンテーションの方針：まとめるか、分割するか

ドキュメンテーションの分割方針としては、以下2つがあります。

1つのドキュメントに多くの情報をまとめる：これは、すべての情報が一つの場所に統一され、直感的にアクセスできるという利点があります。
ドキュメントを階層化して分割する：一つの情報の中に階層を設け、その階層の配下にいろいろなドキュメントをまとめる方法です。これは情報をより詳細に整理し、特定の主題について深く学ぶことができる利点があります。

それぞれのメリット・デメリットを簡易的にまとめました。
詳細については後述します。

対応方針	メリット	デメリット
ドキュメントを階層化して分割する	1. 各ドキュメントに一つの目的が明確になる。 2. 特定の情報を探すのが容易になる。	1. ドキュメントの発見性が低下する。 2. メンテナンスが困難になる。 3. 似たドキュメントが乱立する可能性がある。 4. ドキュメントの信頼性が低下する。 5. 似た内容が書かれたドキュメントに気づきにくくなる。
1つのドキュメントに多くの情報をまとめる	1. ドキュメントの発見性が上がる。 2. メンテナンスが容易になる。 3. ドキュメントの乱立を防げる。 4. ドキュメントが読まれやすくなる。	1. ドキュメントの情報量が膨大になる。 2. 検索に該当しづらくなる。

階層化されたドキュメンテーション

階層化されたドキュメンテーションとは、一つのディレクトリに対して、複数のサブディレクトリがあり、その中に複数のドキュメントが存在するような状態です。

ドキュメンテーションA
   └ ネストされたドキュメンテーションA
      └ さらにネストされたドキュメンテーションA
      └ さらにネストされたドキュメンテーションB
      └ さらにネストされたドキュメンテーションC

階層化の弊害と具体的な問題点

しかし、階層化が深くなると、ドキュメンテーションの管理が困難になるという弊害があります。これは、情報の探索やアクセスが難しくなる可能性があるため、この点に注意が必要です。

階層化の弊害について詳しく話すと、主に以下の三つの問題があります。

1. ドキュメントの発見性が低下

階層が深くなると、読み手にとってドキュメントを探す手間が増えます。一覧性のあるドキュメントでは一覧ページからすぐにアクセスできますが、深い階層では読み手から見つけられない状態になる可能性があります。結果として、メンテナンスが行き届いていても読まれない可能性が出てきます。

ドキュメンテーションA
   └ ネストされたドキュメンテーションA
      └ さらにネストされたドキュメンテーションA # <- リンクをたどらないと気づけない
      └ さらにネストされたドキュメンテーションB # <- リンクをたどらないと気づけない
      └ さらにネストされたドキュメンテーションC # <- リンクをたどらないと気づけない

2. ドキュメントのメンテナンスが困難

階層化されたドキュメントは、メンテナンスする側からも発見しにくくなります。これにより、ドキュメントが古くなっても気づかれずに放置される可能性があります。ドキュメントは常に更新されなければ、古い情報として利用されてしまうことがあるため、これは大きな問題です。

ドキュメンテーションA
   └ ネストされたドキュメンテーションA
      └ さらにネストされたドキュメンテーションA # <- リンクをたどらないと気づけないためメンテされない
      └ さらにネストされたドキュメンテーションB # <- リンクをたどらないと気づけないためメンテされない
      └ さらにネストされたドキュメンテーションC # <- リンクをたどらないと気づけないためメンテされない

3. 似たようなドキュメントの乱立

ドキュメントが発見しにくい状態が続くと、似たようなドキュメントが乱立する問題が発生します。ドキュメントを発見できなかったために新しく作成されたドキュメントと、既存のメンテナンスされていないドキュメントが並存する結果となります。後からこれらを見つけた人は、どちらが更新されているのかを判断しきれない可能性があります。

ドキュメンテーションA
   └ ネストされたドキュメンテーションA
      └ さらにネストされたドキュメンテーションA # 
      └ さらにネストされたドキュメンテーションB # 
      └ さらにネストされたドキュメンテーションC # <- リンクをたどらないと気づけない
   └ 「さらにネストされたドキュメンテーションC」に似たネストされたドキュメンテーションB <- ほぼ一緒

4. ドキュメントの信頼性が低下

メンテナンスされていない古い情報が混在しているドキュメントが多い場合、ドキュメントの信頼性が低下します。信頼性が落ちると、読み手はそもそもドキュメントを読まなくなる可能性があります。結果として、階層化が深いドキュメントは読まれなくなる可能性が高まります。

ドキュメンテーションA
   └ ネストされたドキュメンテーションA
      └ さらにネストされたドキュメンテーションA # 
      └ さらにネストされたドキュメンテーションB # 
      └ さらにネストされたドキュメンテーションC # <- 古い情報かも？と疑われる
   └ 「さらにネストされたドキュメンテーションC」に似たネストされたドキュメンテーションB

5. 重複したコンテンツが混在する

重複したコンテンツが混在する可能性が高まります。具体的には、ドキュメンテーションAとドキュメンテーションBが存在し、次にドキュメンテーションCを作る場合、AとCにはほぼ同じ内容が書かれているかもしれません。しかし、分けて書いた結果として、AとCが同じことを書いていることに気づかない状態が生まれる可能性があります。結果として、マニュアルの情報や業務全体の情報が重複したり、微妙に異なる内容になる可能性があります。これはドキュメントを分けすぎたときに起こる問題で、ドキュメントごとに異なる内容が書かれる状態が生まれやすくなります。

ドキュメンテーションA
   └ ネストされたドキュメンテーションA
      └ さらにネストされたドキュメンテーションA # 
      └ さらにネストされたドキュメンテーションB # 
      └ さらにネストされたドキュメンテーションC # 
   └ 「さらにネストされたドキュメンテーションC」に似たネストされたドキュメンテーションB <- コンテンツの重複

階層化の課題解決方法

これらの課題を解決する方法について二つ提案します。

1. 極力一つのドキュメントにまとめる

階層化せずに一覧的なドキュメントにまとめる方法です。これにより、読み手は一つのページを見て情報を得ることができます。また、メンテナンスも一つのページに集中し、古い情報に対する更新が容易になります。同様に、ドキュメントの乱立や信頼性の低下を防ぐことができます。さらに、似た内容を書いたドキュメントが存在しても、読む過程でそれに気づくことが容易になります。

ドキュメンテーションA <- 全部含める

2. ドキュメンテーションの階層化を2階層までに制限する

この方法は、必要に応じてドキュメンテーションを分ける場合に用いられます。人間は基本的に2階層までの情報にアクセスしやすいですが、それ以上の階層になるとアクセスが難しくなります。そのため、情報を2階層以内に留めることで、メンテナンスの困難さを減らし、読み手がドキュメンテーションを見つけやすくすることが可能です。

この2階層制限の具体例として、GitHubのリポジトリにおけるREADMEやNotionのトップディレクトリが挙げられます。これらの場所には、必要なリンク集をまとめ、必要な情報がすべて含まれる状態を作ります。また、適切なタイミングで必要なリンクにアクセスできるようにすることで、一覧ページ以外からも情報にアクセスできるようにすることが重要です。

ドキュメンテーションA
   └ ネストされたドキュメンテーションA
   └ ネストされたドキュメンテーションB
   └ ネストされたドキュメンテーションC
   └ ネストされたドキュメンテーションD
   └ ネストされたドキュメンテーションE
   └ ネストされたドキュメンテーションF

一つのドキュメントにまとめる方針について

マニュアルのドキュメントを一つにまとめる方針について説明します。

メリット

一つの記事にまとめることのメリットは以下の通りです。

ドキュメントの発見性が向上：すべての情報が一つの場所にまとまっているため、必要な情報を見つけやすくなります。
メンテナンス性が向上：ドキュメントが常に参照されるため、古い情報や問題点をすぐに修正することができます。
重複したドキュメントの乱立を防止：似たようなドキュメントが作成されることを防ぎます。

デメリット

一つの記事にまとめることのデメリットもいくつか存在します。

情報量が膨大になる：一つのドキュメントに多くの情報をまとめると、読む際にどこから読めばよいのかを見つけるのが難しくなる可能性があります。
検索に該当しづらい：全文検索に対応していない場合、特定の情報を探すのが難しくなる可能性があります。

デメリットへの対応方法

一つの記事にまとめる方針のデメリットに対する対策を以下に提案します。

1. 適切な目次を作成する

情報量が膨大になる問題に対しては、適切な目次を作成します。目次から必要な情報に直接ジャンプできるようにすることで、読み手が欲しい情報にすぐにアクセスできます。また、ドキュメントを共有する際にも目次のリンクを使用することで、他の人が情報にアクセスしやすくなります。

2. 見出しにリンクを付ける

見出しにリンクを付けることも有効です。具体的には、あるトピックについて他の人と情報を共有したい場合、該当する見出しにリンクを貼ることで、他の人が必要な情報に直接アクセスできます。

3. 2階層までの情報整理

2階層までの情報整理も有効な手段です。一覧性を確保しつつ、必要最低限の分割を行うことで、一つの記事に情報をまとめつつ、読み手が必要な情報にアクセスしやすくなります。これにより、一つの記事に情報をまとめるという方針を実現しつつ、情報が検索可能であり、ドキュメントの分割も適度に保つことができます。

ChatGPTで5分で作成したものなので、あまり編集できていないですがメモ書きでまとめておきます。
https://chat.openai.com/share/aa68c4d8-ce76-486c-8017-aa76e37638f9

ドキュメンテーションは階層を分けて分割するべきか、1つのドキュメントにまとめておくべきか