私は朝の一杯がかかせません。
熱いコーヒーを注ぐマグは、iittala (イッタラ) のTeemaです。
ブレません。
プロジェクトのドキュメント管理はまともに取り組むと膨大なコストがかかってしまいます。
「 デバッグよりも、ドキュメント作成よりも、ガシガシ実装している方が楽しい 」と思うのは、ほとんどのプログラマが同じでしょう。
だからこそ、周辺の作業はできるだけ短時間でこなしてしまいたいものです。
先日「 Markdownでドキュメントを管理したら楽だなー 」と考えましたので、調べたことをまとめてみます。
Markdownはコストが低い
Markdown使ってますか？
Markdownとは「文書を記述するための軽量マークアップ言語」です。
言語というと大げさに感じるくらい、 覚えることが少なく かつ、簡単にテキストを整えることができることがメリットです。
これをドキュメント管理に利用しない手はありません。
ドキュメントを読むのはエンジニアだけではない
そこで問題になってくるのが、非エンジニアさんへの対応です。
なかなか非エンジニアのお客さまに「Markdownビューア入れればOKですよ」とは言えませんよね。
そういったことを踏まえると、Markdownではなく、他にドキュメントを閲覧できる方法を提供することがベターです。
エディタによってはプレビューをHTML出力することもできますが、ドキュメントの枚数が多くなった時のことを考えると、これは現実的な対応方法ではないことがわかると思います。
面倒くさいと感じたら、やがてやらなくなるのが常です。
Pandocで変換する
そこで、ドキュメント変換ツールPandocです。
http://pandoc.org/MANUAL.html
PandocはHaskell製のドキュメント変換ツールで、対応フォーマットが豊富なことが特徴です。
Pandocをインストールする
以下を参照してインストールを行ってください。
http://pandoc.org/installing.html
私はMacの環境にbrewでインストールしました。
1brew install pandoc
依存ライブラリも少しあって、 インストール完了まで30分程度かかっていました。。。
ドキュメントを変換する
1$ pandoc -o input.md output.html
Pandocの導入については、こちらの記事を熟読いたしました。
http://qiita.com/sky_y/items/80bcd0f353ef5b8980ee
ディレクトリごと処理する
Pandocはファイルを1点ずつ処理するコマンドのため、単体でディレクトリごと処理することは難しそうです。
しかし、なんてことはありません。
ディレクトリごと処理するようにシェルを組めば良いだけの話です！
探してみると、ズバリそのものを公開されている方がいらっしゃいました。
finelagusaz/md2html.shをほぼそのまま利用しております。 ありがとうございます。
最終的にcss指定などを追加してpancodコマンドをこのようにしております。
1pandoc -f markdown_github -i $mdfile -o $htfile -c github.css -t html5 -s
さらに、出力ディレクトリを分けるなど、カスタマイズをするとさらに使い勝手が良くなりますね。
実例：API仕様書を管理する
ディレクトリ構成例
1repository
2 |- webapp
3 | |- プログラム類
4 |
5 |- documents
6 |- API仕様書
7 |- structure
8 | |- 構造体1.md
9 | |- 構造体2.md
10 | :
11 |
12 |- index.md
13 |- Overview.md
14 |- API1.md
15 |- API1.md
16 :
API仕様書_カード詳細取得.md
1## API名
2カード詳細取得
3
4## URL
5/user/card
6
7## リクエスト
8### メソッド
9GEST
10
11### パラメーター
12- user_id
13- card_id
14
15## レスポンス
16### 構造
{ “status” : int, “message”: string, “params” : { “userCard” : {構造体:UserCard} } }
1
2## エラーコード
3- 101 : ユーザID不正
4- 102 : カードID不正
API仕様書_構造体UserCard.md
1## 構造体
2### 構造体名
3UserCard
4
5### 構造
6'```
7userCard : {
8 "userId" : int,
9 "cardId" : int,
10 "atk" : int,
11 "def" : int
12}
13'```
14
15
16### 型
17|Key|Value型|説明|備考|
18|:--|:--|:--|:--|
19|userId|int|ユーザID||
20|cardId|int|カードID||
21|atk|int|攻撃力|1-999|
22|def|int|防御力|1-999|
変換
1$ cd path/to/repository
2$ sh comvert.sh documents/API仕様書
こんな感じでコンバートを実行すると、API仕様書ディレクトリ以下にHTMLが出力されます。
index.mdに各ドキュメントのリンクを用意しておけば、ブラウザで各ドキュメントを横断的に閲覧できストレスもありません。
このindex.mdは手動で編集をしていますが、ファイルの増減が激しければ自動化を検討してコスト減を真面目に考える必要があります。
さらに拡張する
正直にMarkdownから様々なフォーマットに変換できますので、ちょこっとスクリプトを書き足すことで利用できるシーンはかなり広がります。
具体的にはこんな物を用意すればプログラムの補助まで補うことがで、全体のコスト減に貢献できるのではないでしょうか。
- プログラムのenumを舐めて表にまとめる
- mdファイルからJavaのBeanや構造体.hを生成する
おわりに
Markdownに慣れてくると、素早くドキュメントを管理できます。
私もMarkdownの使い始めは、最初はしょっちゅう記法を忘れてしまいqiitaのチートシートをチェックしていました。
http://qiita.com/Qiita/items/c686397e4a0f4f11683d
良いものは積極的に使っていきましょう。
