ドキュメントを整理・改善したい

[PickledChair]

内容

ドキュメントの整備を進めたいという Issue がいくつかあり、それらを連動させて改善すると効率が良いかもしれないと考えました。

ドキュメントの想定読者は以下の２通りが考えられます：

• VOICEVOX CORE の開発者
• VOICEVOX CORE の利用者（VOICEVOX CORE を利用したアプリケーションの開発者）

特に後者に向けたドキュメントの整備について、今後需要が増していきそうです（以下は例）：

• APIドキュメントがイケていない #277
• 使い方を案内する #358
• READMEのAPIのドキュメントは分かりやすい場所に置いてほしい #490

改善の方針として、次の２通りを考えました：

1. 現在ある README 等の記載を整理して見やすくするにとどめる

• Pros: 現状とメンテナンスコストはそれほど変わらない（ファイルが増えるとしても、適切な単位にファイルを分割した分くらいであると考えられる）
• Cons:
  • 書かれている事項が多くなると、markdown ではドキュメントの構造が把握しづらくなり、どこに何が書いてあるのかがわかりづらくなる（現状の README でもある程度複雑になって来ているため、 READMEのAPIのドキュメントは分かりやすい場所に置いてほしい #490 のような Issue が作成された）
  • リポジトリの複数のディレクトリにドキュメントが散らばっている（開発環境の構築、ダウンローダーの使い方、example のビルド方法など）ため、その意味でも一覧性は低い。特に API ドキュメントの場所は分かりづらい

2. 1. に加え、各ドキュメントへアクセスできるドキュメントサイトを作成する

• Pros:
  • ドキュメントの一覧性が高まり、読者が全体を見通しやすくなる
  • ドキュメントをより読みやすいフォーマットで提供することができる
  • README を最低限の記述に留め、詳細を含めた網羅的な情報をドキュメントサイトに集約する（README からもそちらに誘導する）ことによって、README 自体の複雑さを低減して読みやすくすることもできる
• Cons: ドキュメントはプロジェクトのディレクトリ構造とは関係なく書かれると予想されるため、コアの仕様変更時などのドキュメント更新に関してメンテナンスコストは上がる

実現方法

1. の方法をとる場合は今まで通り markdown の編集のみ行う

2. の場合、何らかの静的サイトジェネレータを使う。FastAPI のドキュメントなど、ドキュメントサイトの作成でよく使われている mkdocs-material は、多少拡張された仕様の markdown で記事を書けるため候補の１つとして考えられる

また、API ドキュメント (C API, Python API) に関しては既存の生成方法をそのまま使い、内容の充実を目指す

備考

• READMEのAPIのドキュメントは分かりやすい場所に置いてほしい #490 (comment) で「実際、ライブラリのドキュメントページには、使用にあたってのGetting Startedがよく用意されているイメージ」と書かれていたのを見て、いっそのこと本当に Getting started の記事を書いてしまっても良いのではないか、と考えたのが本 Issue 作成のきっかけです
• 1. の方法で十分である可能性は割とあるので、他の方の意見もよく聞きたいです（ READMEのAPIのドキュメントは分かりやすい場所に置いてほしい #490 (comment) でも「コア開発にあたってのドキュメントをdocs/DEVELOPMENT.mdみたいな感じで分けるのもいいんじゃないかなと思います」とあり、まずはそれで十分なような気もしています）。
• 本 Issue と直接の関係はないですが、 VOICEVOXにおける各ドメイン用語の定義書制作がしたい voicevox_project#27 で取り上げられているような用語の使い方については気をつけて取り組みたいです
• サイトを作るとどんな感じになるか気になったので、mkdocs-material で試しにサイトのガワだけを書いてみたものが以下の画像です（内容は適当で、あくまでイメージですが……）。

[Hiroshiba]

まとめありがとうございます！！

ゴールを定めて、そのゴールを達成できる方法を通るのが良いのかなと思いました！

コアのドキュメント整備のゴールは、例えば 結構プログラミングなどに慣れている人が、一般的な開発環境で特に迷うことなく音声合成できる ようにする、とかでしょうか。
これなら @PickledChair さんの言う1を丁寧に行えば十分達成できそうに思いました。

ユーザーにとって1と2の選択で変わるのは、ドキュメントの見やすさだと思います。
ドキュメントが見やすいと、実装のハードルが下がる・信頼感を上がる効果がありそうです。つまり他の音声合成ライブラリではなくVOICEVOXを選んでもらいやすくなると思います。このあたりをゴールにする場合は2が適している気がします！

個人的にはいったん１をやっちゃうのが良いのかなーと思いました！
で、どうしてもやっぱり見づらかったり案内しづらかったりしたら、かっこいいドキュメントページの作成を目指すとかかな～と思いました！