1. Sphinx + blockdiagで始めるドキュメント生活 小宮 健 (@tk0miya) 2011-05-13

2. 自己紹介 小宮 健 (@tk0miya) 株式会社タイムインターメディア所属 技術者募集中してます！ 普段は PHP, Python, Perl, Ruby などを書いています Sphinx-users の方から来ました

3. はじめに このスライドの内容 ドキュメント、書いてますか？ Sphinx でドキュメントを書こう Excel を捨てよ、blockdiagを使おう 資料はあとで会社のブログにアップします http://labs.timedia.co.jp/ “TIM Labs” で検索してください

4. ドキュメント、書いてますか?

5. 辛い現実 夢の中では、あったような… あればとっても嬉しいなって 運用で対応も、あるんだよ ドキュメントなんてあるわけない 白紙のドキュメントと向き合えますか こんなの絶対おかしいよ

6. 誰のためのドキュメント? 2 種類のドキュメントが存在する 納品物としてのドキュメント (= お客さんのもの) 設計/運用のためのドキュメント (= 自分たちのもの) 足りないのは「設計/運用のドキュメント」 時間、コスト、ノウハウ不足で書けない トラブルや引き継ぎの時に必要だと気づく 喉元が過ぎて熱さを忘れちゃうことも多い

7. メンテできるドキュメントが大事 そのドキュメント、メンテナンスできてますか? 合ってないテーブル定義 足りない機能一覧 キャプチャが古いマニュアル 更新したいけどコスト/時間が足りない あとで泣くのは自分 もしくは引き継ぐ羽目になった誰か 書いて終わりではなく、メンテできる大きさが大事 立派である必要はない ドキュメントだって Lightweight 重要

8. Lightweight なドキュメント ツールをうまく使う Sphinx、Wiki で書く ソースに埋め込む (POD, Javadocなど) やり方を変える テンプレートを使ってスタートダッシュする ドキュメントサンプル @ Sphinx-users 常に書き換える (Wiki 方式) 無理なく、楽しく、続けられるドキュメントであること

9. ここまでのまとめ 設計/運用のためのドキュメントを書こう 書いてないのであれば書き始めよう 更新していないのであれば更新しよう 無理なく、続けられる方法が必要 Lightweight なドキュメントを書こう

10. Sphinx でドキュメントを書こう

11. Sphinx でドキュメントを書こう Sphinx はドキュメントを作成するためのツール reST形式で文書を書くと、様々な形式に変換できる

12. Sphinx の特徴(1) 読み書きしやすい reSTフォーマット 書きたいものがシンプルに書ける 様々な形式に変換できる make コマンド一発で変換できる make html, make pdf, make epub … レイアウトなどの余計なことに煩わされない 見栄えが整っていて気分がいい ページ間の相互リンク (自動索引、参照)

13. Sphinx の特徴(2) 強力なコードハイライト Perl, C++, Python などプログラムコード nginxの設定ファイルなど 拡張機能が豊富 graphviz, aafig, gnuplot, plantumlなどを組み込める ドキュメントが日本語化されている 豊富な利用実績

14. 他ツールとの比較(1) Word フリーフォーマットで書ける スペル/文法チェック、差分管理などの校正機能が充実 複数人での編集には不向き Excel フリーフォーマットで書ける 方眼紙として図を書く人も多い 複数人での編集には不向き

15. 他ツールとの比較(2) POD POD フォーマットで書く テキストでも perldoc経由でも HTML としても読みやすい モジュールのドキュメントによく使われる VCS を使えば複数人で編集できる Sphinx reSTフォーマットで書く テキストでも変換しても読みやすい アプリのドキュメントによく使われる VCS を使えば複数人で編集できる

16. Sphinx の利用例 Python http://docs.python.org/ Sphinx http://sphinx-users.jp/doc10/ groongaドキュメント http://groonga.org/docs/index.html TortoiseHg http://tortoisehg.bitbucket.org/manual/2.0/ Bazzarドキュメント http://doc.bazaar.canonical.com/ja/index.html Symfony2 ドキュメント日本語版 http://docs.symfony.gr.jp/symfony2/

17. ここまでのまとめ Sphinx をおすすめします。 テキストベースなので読み書きしやすい 様々な形式に変換出来る いろんなプロジェクトで利用されている Lightweight ドキュメンテーションを体現するツール

18. Excel を捨てよ、blockdiagを使おう

19. Excel を捨てよ、blockdiagを使おう ドキュメントには図が付きもの システム構成図 画面遷移図 フローチャート UML 系の図 (クラス図、シーケンス図など) ネットワーク図 これらの図をどんなツールで書いていますか?

20. よく使われる作図ツール Excel Visio Powerpoint Photoshop UML 系作画ツール (astah* など) ASCII アート的ななにか

21. Excel 方眼紙時代の思い出

22. 苦労 その１：追加/削除が大変 ここに 1 画面追加

23. 苦労 その１：追加/削除が大変 １.スキマを作る

24. 苦労 その１：追加/削除が大変 ２.図形を置く ３.矢印を調整

25. 苦労 その２：ずれる

26. 苦労 その２：ずれる

27. 苦労 その２：ずれる

28. 苦労 その２：ずれる

29. というわけでExcel の代わりのツールを作りました

30. blockdiagシリーズ テキストを図に変換するツール群 blockdiag：ブロック図 seqdiag：シーケンス図 actdiag：アクティビティ図 nwdiag：ネットワーク図 今までのツールで困っていたことを解決する 自動レイアウトで変更が簡単 テキストデータなので編集しやすい 見栄えは変わらない Graphvizに着想して作った

31. blockdiagの例 このテキストが… diagram { A -> B -> C; B -> D; }

32. blockdiag の例 こうなる

33. seqdiagの例 このテキストが… diagram { browser => server; }

34. seqdiag の例 こうなる

35. netdiagの例 このテキストが… diagram { network global { address = "210.x.x.x/24”; web01; web02; } network dmz { address = "172.x.x.x/24”; web01; web02; db01; db02; } }

36. netdiag の例 こうなる

37. blockdiag：三つのキーワード スピード 構成を書くだけで図が生成される 配置など余計なことに煩わされない メンテナンス性 自動レイアウトのため並び替えが不要 モチベーション 気軽に書いて共有できる スピード感があるので楽しい

38. blockdiagで書けること (1) 各要素ごとに色、画像、矢印の向きなどが設定できる 背景色、線の色、実線/点線 背景画像 矢印の向き

39. blockdiagで書けること (2) そのほかの装飾 ノードのグルーピング 遷移の説明文 (短め)

40. blockdiagで書けること (3) ノードの shape 属性を指定する node1 [shape = “roundedbox”] 基本系

41. blockdiagで書けること (4) ノードの shape 属性を指定する node1 [shape = “roundedbox”] フローチャート系

42. blockdiagで書けること (5) ノードの shape 属性を指定する node1 [shape = “roundedbox”] その他

43. blockdiagシリーズの利用例 blockdiag 画面遷移図: http://bit.ly/lZkszJ ブロック図: http://bit.ly/kYpK6Y フローチャート: http://bit.ly/m7fLsM 組織図: http://bit.ly/l6OOhZ seqdiag: http://bit.ly/lwvEox 変な使い方: http://bit.ly/gMCskC nwdiag: http://bit.ly/kR5tYF

44. ドキュメント連携(埋め込み) blockdiagシリーズは各種ツールと連携できる Sphinx Redmine (Wiki ページ内) Trac (Wiki ページ内) moinmoin Web API (jsonp)

45. デモ ブラウザ上で動くバージョン (Interactive Shell) を利用 Google Appengine上で動作 SVG 出力しているので IE では見えません http://blockdiag.appspot.com/

46. まとめ ドキュメント、書いてますか？ ドキュメントは楽して楽しく書こう ツールややり方を工夫するとドキュメントは辛くない Sphinx は冴えた一つのやり方 もちろん blockdiagシリーズもおすすめ 楽するためにはもっと知恵と経験が必要 テンプレート、ツール群 知識やアイディアください (@tk0miya まで)