README駆動開発というものを知り、Honkit(Gitbook)と組み合わせれば、自分が長年課題に思っていたリポジトリ内の探索に対するソリューションが提供できると考えた。
先にREADMEを作ることで、作りたいものの要件を整理したり、ソースコードのドキュメント漏れを無くせる。
読み手を意識して、分かりにくい状態になっていないかを内省できる。
といったメリットがある。
UIのあるアプリのコードを修正するときは、いつも画面のここのコードはどこなのかを周辺のラベルを元に探さないといけない。
ちゃんとしたところなら、画面IDとか部品IDとか振って、ドキュメントとコードに書いている。
しかし、開発者からすると、このドキュメントを書くという行為が面倒で、端折られがち。
自分だって書きたくない。
ただし、コードのdocstringのように、コードとドキュメントが近いときにはやる気が出ると自分は感じている。
実際、良いコードとされるものにはdocstringがキチンとついてる。
ドキュメントの問題として、管理が別になっていて、コードから遠くなり、同期されにくいことがある。
「Googleのエンジニアリング」で読んだが、Googleの場合は社内Wikiにドキュメントがあり、コードからそこにリンク貼ってるらしい。
また、ファイルのツリーという構造は名前しかなく、メタ情報を持たないので、検索手段が文字による方法しかない問題もある。
すべてのディレクトリにREADME.mdを置いて、Honkitで収集した結果をドキュメントとすれば、コードとドキュメントが近くなりメンテしやすくなるのではないか。
Viewの説明ドキュメントには画像を埋め込み、画面対コードの対応リストを提供できる。Modelの説明ドキュメントにはクラス図やシーケンス図を埋め込み、アルゴリズムの解説を提供できる。ControllerかPresenterの説明ドキュメントには、コミュニケーション図を埋め込み、ViewとModelとの関わりの解説を提供できる。
これらがHTMLドキュメントとして生成されれば、画像やクラス図などを巡回して探し、目的のファイルに到達できる。
ファイル名見て、開いてみて、違ったというストレスが減るのではないか。
画像はbase64エンコーディングして埋め込めばファイルは増えない。
SVGをxmlで埋め込めばファイルは増えないし編集も可能な状態で残せる。
クラス図やシーケンス図はplantUMLで埋め込めばファイルは増えない。
ビューアはHTMLなので、見るだけの人はVSCodeとかセットアップしなくていい。
課題としては、Summaryを自動生成しないと利便性が落ちる。
プラグインあったかな？->あったgitbook-plugin-summary
あと、ルートにHonkitやNode.jsのファイルが足されてしまうので、Node.jsで動いていると誤解されたり、ドキュメントだけでソースがないと誤解されそう。
- book.json*
- package.json*
- node_modules*
- README.md
- SUMMARY.md*
- View
- README.md
- source.code
- Main
- README.md
- source.code
- Feature1
- README.md
- source.code
- Feature2
- README.md
- source.code
- Model
- README.md
- source.code
- Controller
- README.md
- source.code
いいアイデアかなと思ったが、実際にやってみないと、どんな感触かわからない。
ちょっと大きめのリポジトリ作るときには試してみようかな。