add: README.md を構造化

[tarepan]

内容

文量の増えた README.md を構造化・分割する際の方針を議論したい。

背景

そういえば、reamdeをどういうものにするか迷ってます。
ちゃんと考えきれてないのですが、いろんなリポジトリをざっと見た感じ、api利用者向け・貢献者向け・マルチエンジン開発者向けのドキュメントを作り、それらへのリンクをreamdeから張るような形が多そうでした。
加えてアピールしたいことを簡単にreadmeでアピールするとか…？（curlだけで音声合成できますみたいな）

たぶんreadmeの最終形を考えてそれに従って作っていくのが良いんだろうな〜と思いつつ、ちょっとできてない感じです

Hiroshiba, #1096 (review)

Pros 良くなる点

• 文量による初学者への圧迫感 ↓
• 検索性の向上

Cons 悪くなる点

• 複数ファイルへの情報分散

実現方法

• 構造決定
• 分割基準決定
• 分割 & リンク

[Hiroshiba]

Cons 悪くなる点
複数ファイルへの情報分散

そうなんですよね、一覧性は上がるけれども情報が分散しちゃうんですよね。

---

どういう設計思想にすればいいですかね･･･。
ユーザーが欲しい情報にたどり着けるの最大化する･･･？
となると情報が散らばった場合、欲しい情報に一瞬で行けるようなREADMEにしないとですかね。
よくある一番上にリンク集を作って、スクロールをせずに大多数の人は目的の箇所にたどり着けると良さそう。

となると、ファイルを分ける前に1回一番上にリンク集だけ作っても結構解決するかも･･･？

[tarepan]

設計思想 ... ユーザーが欲しい情報にたどり着けるの最大化

👍
同意です。
「ユーザー離脱数を最小化する」+「ユーザー情報到達速度を最大化する」でこれが実現できると思います。

リンク集は後者に寄与するので効果大だと考えます。
前者の離脱は「ドキュメント多くてつらみ…」で発生しがちなので、よくあるパターンは「ターゲットユーザーごとのドキュメント分割」かと思います。USER_GUIDE.md / DEVELOPER_GUIDE.md / CONTRIBUTING.md に分割し、README.md は ENGINE そのものの紹介+リンクに留めるとか。

[Hiroshiba]

良いと思います！

細かいですがDEVELOPER_GUIDE.mdは貢献者が間違えて読んじゃいそうですね。
もうMULTIENGINE_GUIDEとかにしちゃって、あと中身も「開発の詳しいことはCONTRIBUTING.md見て」とかで良いかもと思いました！

[tarepan]

着手します。