Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

手軽にメンテナンスできるドキュメントのヒミツ - blockdiag #odstudy 2011/07

6,574 views

Published on

Published in: Technology
  • Be the first to comment

手軽にメンテナンスできるドキュメントのヒミツ - blockdiag #odstudy 2011/07

  1. 1. 手軽にメンテナンスできるドキュメントのヒミツblockdiagシリーズの紹介<br />Sphinx-users.jp<br />小宮健<br />
  2. 2. 自己紹介:小宮 健<br />仕事<br />(株)タイムインターメディア所属<br />テクニカルオフィサ(技術責任者)として活動<br />参加コミュニティ<br />Sphinx-users.jp<br />Python mini hack-a-thon<br />Sphinx を中心にツールを開発<br />blockdiagシリーズ<br />Sphinx 拡張機能の開発<br />sphinxcontrib-googlechartなど<br />rst2pdf (コミッタ)<br />Twitter: @tk0miya<br />dev<br />
  3. 3. odstudy #1開催おめでとうございます<br />
  4. 4. ドキュメントの必要性<br />
  5. 5. ドキュメントとは?<br />ドキュメント【document】<br />資料的な文書。記録。<br />記録映画。記録文学。<br />コンピューターで、プログラム開発の際に作る仕様書や使用説明書。<br />(goo 辞書より)<br />
  6. 6. ドキュメントとは?<br />IT業界では設計書、手順書、利用マニュアルなどを指す<br />設計書<br />業務の全体像、経緯<br />アーキテクチャやシステム間の連携<br />システム構成、インフラ構成が把握できる<br />手順書<br />メンテナンス手順<br />運用マニュアル<br />利用マニュアル<br />現代のシステムは複雑でドキュメントは必要不可欠<br />
  7. 7. ドキュメント書いてますか?<br />アンケート<br />あなたの担当システム、ドキュメントはありますか?<br />そのドキュメント、更新されていますか?<br />なぜドキュメントを書かないのか<br />忙しい<br />面倒くさい<br />楽しくない<br />
  8. 8. ドキュメント書いてますか?<br />このトラブルが解決したら、ドキュメントを書くんだ…<br />たまに耳にする<br />書いたためしがない<br />
  9. 9. もしドキュメントが無かったら…?<br />ドキュメントが必要とされる場面<br />新しいメンバーが参画するとき<br />他のメンバーへの引き継ぎ時<br />システムのトラブルが発生したとき<br />もしこれらの場面でドキュメントが無かったら…?<br />あとでドキュメントを作ると高いコストを支払うことになる<br />更新されていないと余計な混乱が起きることがある<br />
  10. 10. もしドキュメントが無かったら…?<br />よーく考えよう、ドキュメントは大事だよ<br />
  11. 11. 求められるドキュメントとは<br />必要とされるドキュメントの三つの特徴<br />内容が正確であること<br />簡単に書けること<br />誰もがいつでも参照・更新できること<br />分厚いドキュメントの山では変化に対応できない<br />必要なのはシンプルで変化に耐えうる軽量なドキュメント<br />Lightweight Documentation<br />ドキュメント作りを開発・運用サイクルに組み込む<br />
  12. 12. blockdiagシリーズ<br />
  13. 13. blockdiagシリーズ<br />テキストを図に変換するツール群<br />blockdiag:ブロック図、画面遷移図、フローチャート<br />seqdiag:シーケンス図<br />actdiag:アクティビティ図<br />nwdiag:ネットワーク図<br />blockdiagは定義ファイル(テキスト)から画像を生成する<br />レイアウトは自動的に行われる<br />多くの図形作成ツール(GUI ベース)と異なる考え方<br />細かく並べ替えたい人には向きません<br />
  14. 14. 世にある図作成ツール<br />世にある図を作るツール<br />Excel (方眼紙エディタ)<br />Visio, PowerPoint<br />Cacoo<br />特徴<br />WYSIWYG<br />マウスで要素を配置していく<br />好きな図が書けるけど、並び替えが大変<br />
  15. 15. 追加/削除が大変<br />ここに 1 画面追加<br />
  16. 16. 追加/削除が大変<br />1.スキマを作る<br />
  17. 17. 追加/削除が大変<br />2.不要な矢印を消す<br />
  18. 18. 追加/削除が大変<br />3.図形を配置する<br />
  19. 19. 追加/削除が大変<br />4.矢印を調整<br />
  20. 20. ずれる<br />
  21. 21. ずれる<br />
  22. 22. ずれる<br />
  23. 23. ずれる<br />
  24. 24. ずれる<br />
  25. 25. blockdiagシリーズと他のツール<br />Excel 他<br />レイアウトは手動で行う<br />好きなように並べることができる<br />並べないといけない<br />blockdiag<br />レイアウトは自動的に行われる<br />配置のことは考えなくて良い<br />好きなようには並べられない<br />多くの図形作成ツール(GUI ベース)と異なる考え方<br />見てくれよりも中身が重要だよね?<br />
  26. 26. blockdiagシリーズ<br />blockdiagの重要な周辺ツール「Interactive Shell」<br />Web ブラウザを利用してリアルタイムに図を作れる<br />SVG を利用しているため IE 非対応<br />高速に情報を共有するのに向いている<br />Interactive Shell で blockdiagを説明します<br />※ blockdiagは本来コマンドラインツールです<br />
  27. 27. blockdiagの例<br />このテキストが…<br />{<br />トップページ -> ログイン -> マイページ;<br />トップページ -> 商品一覧 -> 商品詳細;<br />}<br />
  28. 28. seqdiagの例<br />このテキストが…<br />{<br /> A => B => C;}<br />
  29. 29. nwdiagの例<br />このテキストが…<br />{<br /> network { web01; web02; }<br /> network { web01; web02; db01; }<br />}<br />
  30. 30. blockdiag:三つのキーワード<br />スピード<br />構成を書くだけで図が生成される<br />配置など余計なことに煩わされない<br />メンテナンス性<br />自動レイアウトのため並び替えが不要<br />モチベーション<br />気軽に書いて共有できる<br />スピード感があるので楽しい<br />
  31. 31. サンプル図<br />blockdiag<br />画面遷移図: http://bit.ly/lZkszJ<br />ブロック図: http://bit.ly/kYpK6Y<br />フローチャート: http://bit.ly/m7fLsM<br />seqdiag<br />http://bit.ly/lwvEox<br />nwdiag<br />http://bit.ly/kR5tYF<br />http://bit.ly/qZvung(ciscoのフリー画像を使用)<br />
  32. 32. blockdiagの周辺ツール<br />blockdiagの重要な周辺ツール「Interactive Shell」<br />Web ブラウザを利用してリアルタイムに図を作れる<br />SVG を利用しているため IE 非対応<br />高速に情報を共有するのに向いている<br />Interactive Shell を利用して、blockdiagをデモします<br />
  33. 33. ドキュメンテーションツールとの連携<br />Sphinx<br />Redmine<br />Trac<br />moinmoin<br />Mediawiki<br />Web API<br />既存のドキュメントに対して簡単に図を埋め込める<br />
  34. 34. 今後の展開<br />新たな図、ドキュメントへの対応<br />システム構成図<br />ネットワーク図 (ラック、ハブ等の物理層)<br />画面定義書<br />他のツールと連携しての自動生成<br />ネットワーク通信のシーケンス図<br />ネットワーク図<br />プログラム構成図<br />
  35. 35. #odstudyに望むもの<br />
  36. 36. どんなドキュメントが欲しいのか<br />章立て・構成の共有と検討<br />現場の情報はさすがに共有できない<br />骨格だけでも共有できないだろうか<br />どんな図を書いているのか<br />私は blockdiagシリーズ等、ツール面でサポートします<br />なにが欲しいのかを教えて欲しい<br />開発は(ユーザの)ワガママドリブン<br />とりあえず要望や意見を挙げて欲しい<br />
  37. 37. #odstudyへの提案(アイディア)<br />こんなものを考えてみてはどうでしょう<br />ドキュメントのテンプレート<br />手間暇のバランスを考えて、松竹梅とか?<br />ネットワーク系の図<br />物理配線<br />ラック図<br />仮想環境を踏まえたネットワーク図<br />
  38. 38. まとめ<br />手軽にメンテナンスできるドキュメントのヒミツ<br />blockdiagシリーズを使いましょう<br />並び替えや位置調整に手間をかけない<br />図を作るのにスピードを与える<br />楽するためには知恵と経験が必要<br />#odstudyで話し合ってみてはどうだろうか<br />ツール面でサポートします。アイディアください<br />URL: http://blockdiag.com/<br />Twitter: @tk0miya #blockdiag<br />Google グループ: blockdiag-discuss<br />

×