#1142 で提案している解説ドキュメントの作成

[nmori]

内容

#1142 で会話したドキュメントを書き起こしてみました。
過不足含めて会話できれば幸いです。

関連 Issue

ref #1142

スクリーンショット・動画など

その他

[nmori]

提出してから気づきましたが　休符のフレーム長が 45ではないので　楽譜とちがっていました。（明日以降修正します）

[Hiroshiba]

プルリクエストありがとうございます！！！
丁寧に書かれていてすごいいい感じだと感じました！！！

一旦大枠で読ませていただき、こうしたらより良いかも？と思ったことをコメントさせていただきます･･･！！

---

流れの整理

ちょっとこれは相談したいのですが、最初に考え方の流れがあるとわかりやすそうかもと思いました！
楽譜→楽譜データ→歌い方データ→歌声という流れで進む、というのが最初にあれば良いかもと。
（もしかしたらこの説明は不要なのかもなので、意見をお伺いしたいです！）

アクセスポイントの取得はエディタの話なので、ここでは軽く説明する方がよいかもと思いました！
GUIのあるVOICEVOXソフトウェアで起動しているエンジンを叩く場合はアクセスポイントが変わる、というのを最後の方に案内するだけでも良いかも･･･？
あとはエディターのドキュメントへのリンクがあると良いかも？
（ファイル名が変わったりしていつのまにかリンク切れになっちゃいそうですが。。。）

あと楽譜はもしかしたら読めない人もまぁまぁいるのではとか思いました！
なので、情報を箇条書きで書いてあげると後の話がわかりやすいかも。「BPMが125」とか、４分休符→４分音符×３→４分休符とか！
それと歌詞は「ドレミ」だと音階なのか歌詞なのかわからないので「テスト」とかもありかも。

文章構造は↓の感じとかどうでしょう。
データを作るところでそのデータを作るための情報の取得方法を説明する、という流れにしてみました。
あまり文章は得意ではないのでちょっと自信ないですが･･･

• （はじめの概要）
  • このドキュメントで何を説明するかの紹介
• APIの送信例
• データの流れ
  • 楽譜→楽譜データ→歌い方データ→歌声音声
• 楽譜データを作る
  • サンプル楽譜紹介
  • 計算に必要な数値の取得
  • 楽譜用JSONデータの作成
• 歌い方データを作る
  • /singersのtypeがsingなものが対応してること
  • クエリの生成
• 歌声音声を作る
  • /singersのtypeがsingとframe_decodeなものが対応してること
  • 歌声の生成

記法の整理

APIエンドポイント(/frame_synthesisなど)とjsonキー(typeなど)と値(nullなど)はコードブロックで囲うと見やすそう。
（それを意図されてそうだけど、バッククォート がふたつあってレンダリングが変になってる･･･？）

例示は「」で囲うようにして見分けられるようにすると見やすそう（60秒あたり 125 回叩かれるリズムなど）

用語の整理

提案されている用語がとても良い感じだと思いました！！
（クエリデータ）となってるとこだけ、（APIドキュメントでは「歌唱音声合成用のクエリ」）と１回だけ説明で良さそうかもです。

あ、歌声は「歌声音声」とするとこれが目的なことがわかりやすいかも！

あとIDとしてる部分は全部スタイルIDに統一するとわかりやすいかも･･･？
（speaker UUIDもあるので･･･）

[nmori]

査読ありがとうございます（配信も先程みました）
コメント頂いた点を中心にドキュメント全体構成を見直します。
（ChatGPTを活用する点も、ちょっと真似して精度あげてみたいとおもいます）

[tarepan]

@Hiroshiba
こちら、レビュアー側でキャッチボールが止まっていそうです。
Sing系に関する優れたドキュメンテーションと感じるので、是非マージ目指したいです。ただ私が Sing 系の詳細を把握しきれていないので、@Hiroshiba さんにレビューを担って頂けるととても嬉しいです（合成の詳細に関する部分以外、例えばドキュメント形式などについてはもちろん私もレビュー貢献できればと）。

@nmori
素晴らしいプルリクエストをありがとうございます！エンジン単体からだと全体像が掴みづらい Sing 系について、図を含めて丁寧に説明されていると感じました。特に frame_length 周りの時間スケールは実ユーザーがとても助かる内容です。
（おそらく VOICEVOX ENGINE 側の都合で 🙇）前回のレビューからかなり時間が空く形になってしまいましたが、もしご都合が合えば、マージへ向けて御助力いただければ幸いです。

[Hiroshiba]

リマインドありがとうございます！！
期間が空いてしまってすみません、近い内にレビューできればと思います！！

[Hiroshiba]

ソング API についての説明はかなり分かりやすい気がします！！
ちょっと足りなそうな点をいくつかコメントさせていただきました！

結構コメントしていますが、どちらかというと文章構造やドキュメントとしての体裁のコメントが主です！
まあでもこの辺り突き詰めると時間がかかりすぎてしまうので、もし @nmori さん的に良いドキュメントを目指すことにご興味があれば、是非お付き合いいただければという気持ちです･･･！！！

ドキュメントとしてどこを目指すかは @tarepan さんにも相談したいです 🙏
（ファシリテーションをお願いできると僕的にはかなり助かります 🙇 ）

---

技術文書の書き方ですが、長くメンテナンスしたり調べたりして色々コツを知っているので、パっと思いつく限り列挙してみました！！
参考になれば･･･！！

• 段落ごとに、主題や結論を先頭に書く
  • 1文目をつなげていくと全体の流れがわかるようにしておく
  • 例えば「フレーム長の考え方」の１文目が「125bpmとは、1分間に4分音符が125回となる速さです」となってるけど、読む側からするとなぜこれを説明されてるかわからないから読みづらく感じるはず
  • 例えば「ソングAPIは長さをフレーム長で指定するので、ここではフレーム長の考え方を説明します」みたいなことを書くと結構わかりやすい･････かも･･･？（ちょっと自信なし）
• 漢字は開く
  • ◯◯が可能です　→　〇〇できます
  • 〇〇を実行します　→　〇〇します
  • 今回の例だと「発話がうまくできない可能性があります」は「ことがあります」とするとおしゃれ
• 接続詞は強調したいときのみ書く
  • 大体の接続詞はいらないのでなくし、強調したい時のみ書くことで強調が効きやすい