1. ドキュメント、書いてますか？ 小宮 健 (@tk0miya) 2011-02-19

2. おまえ誰よ？ 小宮 健 (@tk0miya) 株式会社タイムインターメディア所属 技術者募集中らしいです Python 歴は約 1年ぐらい Sphinx-users の方から来ました 15時ぎりぎりまで資料作ってました 分かりづらかったらごめんなさい！

3. はじめに このスライドの内容 ドキュメント、書いてますか？ Inside blockdiag (と仲間たち) 資料はあとで会社のブログにアップします http://labs.timedia.co.jp/ “TIM Labs” で検索してください

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

5. 理想と現実 ドキュメントは書くべき。 実際のところは？ ドキュメント書く時間がない コスト (リソース) がない そもそも開発が終わらない 口伝でなりたっているプロジェクト = 一子相伝的プロジェクト

6. こんな子いるかな? 「(納品しないから)今回はドキュメントなしで」 「機能一覧に書いてない機能がたくさんある」 「運用でカバーすることにしよう」 「仕様書はあったら嬉しいなって」 「ドキュメントなんて、あるわけない」 「こんなの絶対おかしいよ」

7. 誰のためのドキュメント? 納品物としてのドキュメント お客さんのもの 設計/運用のためのドキュメント 自分たちのもの もしくは引き継ぐ誰かのためものもの 大抵足りないのは設計/運用のためのドキュメント つまり困るのは自分たち！

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

9. Lightweight なドキュメント ツールをうまく使う Sphinx、Wiki で書く ソースに埋め込む -> docstringを Sphinx などで抽出 やり方を変える テンプレートでショートカットする shimizukawaテンプレート @ Sphinx-users 常に書き換える (Wiki 方式) 無理なく、楽しく、続けられるドキュメントであること

10. ここまでのまとめ 設計/運用のためのドキュメントを書こう 書くだけじゃダメ、更新もしなくちゃ。 無理なく、続けられる方法が必要 Sphinx を使おう テンプレート化していこう Excel 方眼紙は止めよう ここのツールを作った

11. Inside blockdiag (と仲間たち)

12. blockdiag テキストから画面遷移図を生成するツール コマンドライン / Sphinx 拡張として動作 悪名高きExcel 方眼紙がイヤで作った 並べ替えるのが面倒、ずれる 、etc…

13. blockdiagの特徴 定義ファイル(テキスト)から画像(PNG, SVG)を生成 Graphvizっぽい文法 (DOT like 文法) 自動的にレイアウトしてくれる 追加/削除が簡単 ずれたりしない 日本語 (UTF-8) 対応 easy_installblockdiagでインストール可能

14. blockdiag の使い方 遷移図の定義を作ります diagram { A -> B -> C; B -> D; } blockdiagコマンドで画像を生成 % blockdiag –o sample.png input.diag

15. Inside blockdiag blockdiagは 4つのパートから構成される パーサ レイアウトエンジン 描画エンジン ノードレンダラー

16. Inside blockdiag：パーサ DOT 文法 (graphviz由来) をまねた文法を採用 diagram { A -> B -> C; B -> D; } テキストでもわかりやすい (like reST!) ノード間の関係や属性をわかりやすく表現できる funcparserlibを利用してパーサを生成 依頼して Python 2.4 でも動くようにしてもらった

17. Inside blockdiag：レイアウトエンジン レイアウトエンジン X 軸(横方向)、Y 軸(縦方向) の順に並べている 説明が大変なので中身は割愛します 自分がきれいだと思うようにレイアウト 完全にヒューリスティック 「見やすさ」は感覚的なもので正解はない イマイチなものを見かけたら教えて下さい

18. Inside blockdiag：描画エンジン blockdiagは PNG/SVG/PDF 形式で出力できる バックエンドには PIL/SVGdraw.py/reportlabを利用

19. Inside blockdiag：描画エンジン PIL っぽいインターフェースで中間層を作っている line, rectangle, arc, ellipse などの API がそろってる 手がかかってる部分 PIL で点線を書けるようにした SVG でテキスト折り返し 影のぼかし部分

20. Inside blockdiag：レンダラー ノードの形状は差し替え可能になっている プラグインを書くことで形状を追加することができる

21. Inside blockdiag：レンダラー 新しいシェイプを足す場合はプラグインを書く 図形を書く、塗る、ラベルを配置する、接点を調整する 図形の組み合わせで簡単に作れる 来週あたりにプラグインの書き方を公開するつもり 是非作って下さい

22. Inside blockdiag：周辺ツール Interactive shell デモツールとして大好評 Appengine上で動いている フォームを書き換える度にリクエストしている Appengineでは PIL が動かないので SVG 出力してる 問題点：blockdiagそのものだと勘違いされてる気がする

23. Inside blockdiag：周辺ツール Web クローラー Pycon mini JP のデモ用に作成 デザイナーさんからキャプチャ画像で遷移図を作るという話を聞いたので作ってみた urllib + lxmlでスクレイプ + クローリング 便利なクローラーライブラリを教えて下さい PyQtでキャプチャ取得 (by ransui先生) 生成される図がでかすぎて閲覧不能 デモ用と割り切って作り捨てることに。

24. Inside blockdiag：周辺ツール Sphinx 言わずもしれた便利なアイツ Sphinx 拡張を使うと reSTに直接埋め込むことができる .. blockdiag:: diagram { A -> B -> C; B -> D; } Sphinx との組み合わせは超便利 (らしい)

25. seqdiag テキストからシーケンス図を生成するツール コマンドライン / Sphinx 拡張として動作 @shimizukawa師匠の指示で作らされた作った

26. ある日のできごと このイラストは実在の団体とは関係ありません Sphinx のドキュメントにシーケンス図を埋め込みたい sdeditを使ったら? -> Java 入れるのイヤ。 作って。なう。

27. blockdiag の使い方 シーケンス図の定義を作ります diagram { browser => server; } seqdiagコマンドで画像を生成 % seqdiag –o sample.png input.diag

28. Inside seqdiag blockdiagコアを利用して 2時間でプロトタイプ作成 1週間かけてちゃんと作り込んだ 以降、絶賛放置中 バグつぶしをしたら開発終了の予定 シンプルに書いて、それっぽい図ができる Blockdiagと同じような周辺ツールがある Interactive Shell Sphinx 拡張

29. schema2rst DB スキーマから定義書を生成する Foreign Key から ER 図っぽいものも生成できる サンプル 以前作った schema2excel.rb を Sphinx 向けにリファイン Rails 風の DB Migration システムと相性がいい気がする 作りながらスキーマを随時拡張していく

30. Inside schema2rst スキーマ情報の抽出 Information_Schemaからごりごり SELECT してるだけ MySQLでコメントを付けておくと表現がリッチに 他の DBMS への対応はそのうち考えます ER 図の生成 dot ファイルを生成して Graphvizに渡してる テーブルが多すぎると図が大きくなって見づらい (体験談) 面倒なので bitbucketで公開してるだけ

31. ここまでのまとめ blockdiagは謎の技術で動いているわけじゃない 普通の Python スクリプト 素直なコードが多いので読みやすいはず 但しレイアウトエンジンを除く 要するに… Contributer募集。 ブロック図とか UML とか好きな人 ドキュメントを楽して書くために苦労できる人 道のりが遠すぎて燃え尽きそうです。助けて

32. 次の目標 ブロック図を作る 機能構成とかシステム構成を表現する図 http://twitter.com/#!/tk0miya/status/36083686684377088 文書テンプレートの作成 みんなが使ってるドキュメントからいいところを抽出 いろんな人から意見を聞きたい！ 書くのが面倒くさくない / メンテするのにちょうどいい量 @shimizukawaを巻き込んで、まとめていきます 興味がある人は声かけてください

33. まとめ ドキュメントは楽して楽しく書こう 自分のために。誰かのために 書いて終わりではなく、メンテできる大きさが大事 ツールややり方を工夫するとドキュメントは辛くない Excel 方眼紙はもはや化石 Sphinx は冴えた一つのやり方 もちろん blockdiag, seqdiagもね 楽するためには知恵と経験が必要 テンプレート、ツール群 知識やアイディアください (@tk0miya まで)