はじめに

プロジェクトのドキュメント配置について、いろいろな選択肢があると思うので整理したい。

github形式のリポジトリ

そもそもなぜドキュメント配置に悩むようになったかと言えば、githubのリポジトリには直下にREADME.mdがあり、ここに概要を書いてwikiにドキュメントを充実させていくので十分なんだっけ？というところから始まる。
１つのリポジトリで完結するようなライブラリはこれでもいいと思う。wikiに画像をupできないが、<プロジェクト名>.wikiとしてチェックアウトする事で画像もコミットできるので、このやり方に慣れれば特に問題ないはず。ブラウザ上で履歴や差分も確認できる。

srcとdocは近い方がいい

元々はprojectリポジトリにdocフォルダを作成して、そこにmdファイルをアップしていた。これはこれでsrcとdocが一リポジトリで完結して収まりが良い。docの名前はdocsの方がしっくりくるとかはこの際どうでも良くて、docの部分もsrcと同じようにプルリクしたりレビューしたり履歴確認できるので業務でチーム開発するにはこれがいいんじゃないのか。
全体としては一つのサービスでもマイクロサービスに分割しておいて、サービス間はjsonやprotocolbufなんかで連携して、各マイクロサービスごとにデプロイできたり、技術的に古くなったりしたら入れ替えたりできるようにしておきたい。
例えばあるサービスではmember/order/productの各マイクロサービスで構成するとしてらこんな感じになる。

member/
  |-doc/
  |-src/
    |-main/
    |-test/
order/
  |-doc/
  |-src/
  ...
product/
  |-doc/
  |-src/
  ...

サービスのドキュメントには各サービスの概要、満たすべき仕様(API仕様書など)や、テスト、デプロイ方法などを記述する。

未だにドキュメントとソースが一対一の関係になるような詳細設計書を書いてる人はほとんどいないと思う。その時間でソース書けるし改修の時に置いていかれてソースとドキュメントが乖離する原因になるからだ。テストについては自動化するとしても、その自動化したテストが要件をすべてチェックしているかどうか確認するための一覧用のドキュメントは欲しいところだ。

プロジェクト全体のドキュメント

srcとdocが近い方がいいとはいえ、要件定義とかアーキテクチャ設計、配置図などプロジェクトを通したドキュメントはどうするか。これらは各マイクロサービスで共通となるので、プロジェクト用docリポジトリを作った方がよくなる。会議の議事録なんかもこのリポジトリに突っ込めばすべてgitで履歴管理できて便利。まあでもプロジェクト管理用に別途JiraでもRedmineでも導入して、そこのwikiで履歴管理した方がわかりやすいか。

偉い人(コードの読めない人)に見せる時用にdocリポジトリは一つになってる方が便利な時もありそう。でもやっぱりマイクロサービスならDB定義やテスト仕様書は各サービスごとに独立しているべきである。でないと一部サービスだけ技術入替とかをする時に影響範囲が多岐に渡ってしまい、改修漏れなどの原因となる。

proj_doc/
|- requirements/
|- architecture/
|- basic design/
|(- management/ ... 管理用)

proj_member/
|- doc/
|- src/

proj_order/
|- doc/
|- src/
...

まとめ

というわけで新しくprojを始める時はまずproj_docを作ってそこに要件定義とか進捗とかを入れていくことになるのね。そして各マイクロサービスに個別のdocを掘る。

前に書いたときと違う結論になってしまったけど、やっぱりこっちの方がいいな。