プロジェクトのドキュメントをgitで管理する

プロジェクトの文書管理は頭痛のタネですが、少しでもエンジニアらしく管理したいですね。

対象は、自社開発プロジェクトレベル、つまり、ドキュメント自体が商品になるわけではなく、あくまで補助ツールという位置付けの、手順、マニュアル、内部仕様などです。

Readmeに書く、コメントに入れる、ソースコード自体をわかりやすくする、などしても管理する必要があるドキュメントは0というわけにはいかないですよね。

試験的に、git+markdownで文書管理したことがあり、使いやすかったので、ドキュメントをgit+markdownに持って行けないか考えました。

以下参考記事

• Subversion で文書やプロジェクトを管理している企業は git に移行すべき http://www.baldanders.info/spiegel/log2/000823.shtml
• 非エンジニアのためのバージョン管理Git http://tonari-it.com/git-merit-preparation/

プロジェクトの文書管理といえば、この辺りがメジャーかと思います。

• Excel（MS Office)
• Trac/RedmineのWiki
• GoogleDocsやEvernoteなどWebドキュメント系

業務がらみとなるとExcelが必須になることが多いですが、それ以外は、基本、使い慣れたgit+markdownにしたいです。

ポイントになりそうなところ

• 扱うデータ
  • テキスト
  • 画像(イメージ・ベクター)
  • バイナリ
• 作成
  • トピック（ページ）の新規作成しやすさ
  • 他のプロジェクト管理ツールとの連携
• 更新
  • 履歴管理
  • ドキュメントの信頼性
  • 更新フロー

この中で、git+markdownが強いのは、更新回りです。 特に、複数人で、継続的に更新をかける場合、プルリクの仕組みがそのまま使えます。

TracなどのWikiに比べると、他のプロジェクト管理ツールとの連携は弱いですが、相互に直リンクを張る、Webhookでチャットへポストするなどのゆるい連携でも十分なイメージです。

逆に弱いのは、画像・バイナリの扱いですね。ここが解消すれば、かなりのドキュメントが移行できるのではないでしょうか。

以下、画像やバイナリを扱う参考記事。

• ファイル共有ソフトとしてのGit、これなら使える http://www.symmetric.co.jp/blog/archives/577
• (StackEdit)Markdownテキストでシーケンス図とフローチャートを描く http://qiita.com/ka215/items/a709665cb34c505ccf1f