sphinx + blockdiag で始めるドキュメント生活 2011/05 yokohama.pm

14,492 views

Published on

Published in: Technology
0 Comments
15 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
14,492
On SlideShare
0
From Embeds
0
Number of Embeds
4,411
Actions
Shares
0
Downloads
51
Comments
0
Likes
15
Embeds 0
No embeds

No notes for slide

sphinx + blockdiag で始めるドキュメント生活 2011/05 yokohama.pm

  1. 1. Sphinx + blockdiagで始めるドキュメント生活<br />小宮 健 (@tk0miya)<br />2011-05-13<br />
  2. 2. 自己紹介<br />小宮 健 (@tk0miya)<br />株式会社タイムインターメディア所属<br />技術者募集中してます!<br />普段は PHP, Python, Perl, Ruby などを書いています<br />Sphinx-users の方から来ました<br />
  3. 3. はじめに<br />このスライドの内容<br />ドキュメント、書いてますか?<br />Sphinx でドキュメントを書こう<br />Excel を捨てよ、blockdiagを使おう<br />資料はあとで会社のブログにアップします<br />http://labs.timedia.co.jp/<br />“TIM Labs” で検索してください<br />
  4. 4. ドキュメント、書いてますか?<br />
  5. 5. 辛い現実<br />夢の中では、あったような…<br />あればとっても嬉しいなって<br />運用で対応も、あるんだよ<br />ドキュメントなんてあるわけない<br />白紙のドキュメントと向き合えますか<br />こんなの絶対おかしいよ<br />
  6. 6. 誰のためのドキュメント?<br />2 種類のドキュメントが存在する<br />納品物としてのドキュメント (= お客さんのもの)<br />設計/運用のためのドキュメント (= 自分たちのもの)<br />足りないのは「設計/運用のドキュメント」<br /> 時間、コスト、ノウハウ不足で書けない<br /> トラブルや引き継ぎの時に必要だと気づく<br />喉元が過ぎて熱さを忘れちゃうことも多い<br />
  7. 7. メンテできるドキュメントが大事<br />そのドキュメント、メンテナンスできてますか?<br />合ってないテーブル定義<br />足りない機能一覧<br />キャプチャが古いマニュアル<br />更新したいけどコスト/時間が足りない<br />あとで泣くのは自分<br />もしくは引き継ぐ羽目になった誰か<br />書いて終わりではなく、メンテできる大きさが大事<br />立派である必要はない<br />ドキュメントだって Lightweight 重要<br />
  8. 8. Lightweight なドキュメント<br />ツールをうまく使う<br />Sphinx、Wiki で書く<br />ソースに埋め込む (POD, Javadocなど)<br />やり方を変える<br />テンプレートを使ってスタートダッシュする<br />ドキュメントサンプル @ Sphinx-users<br />常に書き換える (Wiki 方式)<br />無理なく、楽しく、続けられるドキュメントであること<br />
  9. 9. ここまでのまとめ<br />設計/運用のためのドキュメントを書こう<br />書いてないのであれば書き始めよう<br />更新していないのであれば更新しよう<br />無理なく、続けられる方法が必要<br />Lightweight なドキュメントを書こう<br />
  10. 10. Sphinx でドキュメントを書こう<br />
  11. 11. Sphinx でドキュメントを書こう<br />Sphinx はドキュメントを作成するためのツール<br />reST形式で文書を書くと、様々な形式に変換できる<br />
  12. 12. Sphinx の特徴(1)<br />読み書きしやすい reSTフォーマット<br />書きたいものがシンプルに書ける<br />様々な形式に変換できる<br />make コマンド一発で変換できる<br />make html, make pdf, make epub …<br />レイアウトなどの余計なことに煩わされない<br />見栄えが整っていて気分がいい<br />ページ間の相互リンク (自動索引、参照)<br />
  13. 13. Sphinx の特徴(2)<br />強力なコードハイライト<br />Perl, C++, Python などプログラムコード<br />nginxの設定ファイルなど<br />拡張機能が豊富<br />graphviz, aafig, gnuplot, plantumlなどを組み込める<br />ドキュメントが日本語化されている<br />豊富な利用実績<br />
  14. 14. 他ツールとの比較(1)<br />Word<br />フリーフォーマットで書ける<br />スペル/文法チェック、差分管理などの校正機能が充実<br />複数人での編集には不向き<br />Excel<br />フリーフォーマットで書ける<br />方眼紙として図を書く人も多い<br />複数人での編集には不向き<br />
  15. 15. 他ツールとの比較(2)<br />POD<br />POD フォーマットで書く<br />テキストでも perldoc経由でも HTML としても読みやすい<br />モジュールのドキュメントによく使われる<br />VCS を使えば複数人で編集できる<br />Sphinx<br />reSTフォーマットで書く<br />テキストでも変換しても読みやすい<br />アプリのドキュメントによく使われる<br />VCS を使えば複数人で編集できる<br />
  16. 16. Sphinx の利用例<br />Python<br />http://docs.python.org/<br />Sphinx<br />http://sphinx-users.jp/doc10/<br />groongaドキュメント<br />http://groonga.org/docs/index.html<br />TortoiseHg<br />http://tortoisehg.bitbucket.org/manual/2.0/<br />Bazzarドキュメント<br />http://doc.bazaar.canonical.com/ja/index.html<br />Symfony2 ドキュメント日本語版<br />http://docs.symfony.gr.jp/symfony2/<br />
  17. 17. ここまでのまとめ<br />Sphinx をおすすめします。<br />テキストベースなので読み書きしやすい<br />様々な形式に変換出来る<br />いろんなプロジェクトで利用されている<br />Lightweight ドキュメンテーションを体現するツール<br />
  18. 18. Excel を捨てよ、blockdiagを使おう<br />
  19. 19. Excel を捨てよ、blockdiagを使おう<br />ドキュメントには図が付きもの<br />システム構成図<br />画面遷移図<br />フローチャート<br />UML 系の図 (クラス図、シーケンス図など)<br />ネットワーク図<br />これらの図をどんなツールで書いていますか?<br />
  20. 20. よく使われる作図ツール<br />Excel<br />Visio<br />Powerpoint<br />Photoshop<br />UML 系作画ツール (astah* など)<br />ASCII アート的ななにか<br />
  21. 21. Excel 方眼紙時代の思い出<br />
  22. 22. 苦労 その1:追加/削除が大変<br />ここに 1 画面追加<br />
  23. 23. 苦労 その1:追加/削除が大変<br />1.スキマを作る<br />
  24. 24. 苦労 その1:追加/削除が大変<br />2.図形を置く<br />3.矢印を調整<br />
  25. 25. 苦労 その2:ずれる<br />
  26. 26. 苦労 その2:ずれる<br />
  27. 27. 苦労 その2:ずれる<br />
  28. 28. 苦労 その2:ずれる<br />
  29. 29. というわけでExcel の代わりのツールを作りました<br />
  30. 30. blockdiagシリーズ<br />テキストを図に変換するツール群<br />blockdiag:ブロック図<br />seqdiag:シーケンス図<br />actdiag:アクティビティ図<br />nwdiag:ネットワーク図<br />今までのツールで困っていたことを解決する<br />自動レイアウトで変更が簡単<br />テキストデータなので編集しやすい<br />見栄えは変わらない<br />Graphvizに着想して作った<br />
  31. 31. blockdiagの例<br />このテキストが…<br />diagram {<br /> A -> B -> C;<br /> B -> D;<br />}<br />
  32. 32. blockdiag の例<br />こうなる<br />
  33. 33. seqdiagの例<br />このテキストが…<br />diagram {<br /> browser => server;<br />}<br />
  34. 34. seqdiag の例<br />こうなる<br />
  35. 35. netdiagの例<br />このテキストが…<br />diagram {<br /> network global {<br /> address = "210.x.x.x/24”;<br /> web01; web02;<br /> }<br /> network dmz {<br /> address = "172.x.x.x/24”;<br /> web01; web02; db01; db02;<br /> }<br />}<br />
  36. 36. netdiag の例<br />こうなる<br />
  37. 37. blockdiag:三つのキーワード<br />スピード<br />構成を書くだけで図が生成される<br />配置など余計なことに煩わされない<br />メンテナンス性<br />自動レイアウトのため並び替えが不要<br />モチベーション<br />気軽に書いて共有できる<br />スピード感があるので楽しい<br />
  38. 38. blockdiagで書けること (1)<br />各要素ごとに色、画像、矢印の向きなどが設定できる<br />背景色、線の色、実線/点線<br />背景画像<br />矢印の向き<br />
  39. 39. blockdiagで書けること (2)<br />そのほかの装飾<br />ノードのグルーピング<br />遷移の説明文 (短め)<br />
  40. 40. blockdiagで書けること (3)<br />ノードの shape 属性を指定する<br />node1 [shape = “roundedbox”]<br />基本系<br />
  41. 41. blockdiagで書けること (4)<br />ノードの shape 属性を指定する<br />node1 [shape = “roundedbox”]<br />フローチャート系<br />
  42. 42. blockdiagで書けること (5)<br />ノードの shape 属性を指定する<br />node1 [shape = “roundedbox”]<br />その他<br />
  43. 43. blockdiagシリーズの利用例<br />blockdiag<br />画面遷移図: http://bit.ly/lZkszJ<br />ブロック図: http://bit.ly/kYpK6Y<br />フローチャート: http://bit.ly/m7fLsM<br />組織図: http://bit.ly/l6OOhZ<br />seqdiag: http://bit.ly/lwvEox<br />変な使い方: http://bit.ly/gMCskC<br />nwdiag: http://bit.ly/kR5tYF<br />
  44. 44. ドキュメント連携(埋め込み)<br />blockdiagシリーズは各種ツールと連携できる<br />Sphinx<br />Redmine (Wiki ページ内)<br />Trac (Wiki ページ内)<br />moinmoin<br />Web API (jsonp)<br />
  45. 45. デモ<br />ブラウザ上で動くバージョン (Interactive Shell) を利用<br />Google Appengine上で動作<br />SVG 出力しているので IE では見えません<br />http://blockdiag.appspot.com/<br />
  46. 46. まとめ<br />ドキュメント、書いてますか?<br />ドキュメントは楽して楽しく書こう<br />ツールややり方を工夫するとドキュメントは辛くない<br />Sphinx は冴えた一つのやり方<br />もちろん blockdiagシリーズもおすすめ<br />楽するためにはもっと知恵と経験が必要<br />テンプレート、ツール群<br />知識やアイディアください (@tk0miya まで)<br />

×