ソースに対するドキュメント管理は、wiki+SVNで決定
前回: ソースに対するドキュメントのメンテナンス方法 id:ndruger:20080310#1205097712
要件
- ソースと同期してリビジョン管理ができる
- 画像を張れるなどの表現力がある(シーケンス図やクラス図を使うため)
- 比較が簡単
結論に至った経緯
mediawikiは、SVNのソースとリビジョンを同期する機構がないので面倒だし、txt+SVNでは表現力が少なすぎる。
word+SVNはバイナリファイルの更新をあまりしたくないし、wordは面倒なので嫌だし、html+SVNはhtmlを書くのがめんどう。
具体的な利用方法
ドキュメントを書く
ソースといっしょにチェックアウトしたwiki形式のドキュメントを、好きなエディターで編集する。
ひとりwikiなどを使って、見栄えもチェック可能。
ひとりWiki - ベクターソフトニュース
http://www.vector.co.jp/magazine/softnews/051022/n0510226.html
レビューする
ソースレビュー時にドキュメントもいっしょにレビューする
wiki記法のファイルは見づらいので、htmlに変換してレビューもできるようにする。
cgi+javascriptを使って、簡単にできそう。
JavaScriptでWiki記法のテキストをHTMLに変換する:phpspot開発日誌
http://phpspot.org/blog/archives/2006/09/javascriptwikih.html