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

手軽にメンテナンスできるドキュメントのヒミツblockdiagシリーズの紹介
Sphinx-users.jp
小宮健

自己紹介：小宮健
仕事
(株)タイムインターメディア所属
テクニカルオフィサ(技術責任者)として活動
参加コミュニティ
Sphinx-users.jp
Python mini hack-a-thon
Sphinx を中心にツールを開発
blockdiagシリーズ
Sphinx 拡張機能の開発
sphinxcontrib-googlechartなど
rst2pdf (コミッタ)
Twitter: @tk0miya
dev

odstudy #1開催おめでとうございます

ドキュメントの必要性

ドキュメントとは?
ドキュメント【document】
資料的な文書。記録。
記録映画。記録文学。
コンピューターで、プログラム開発の際に作る仕様書や使用説明書。
(goo 辞書より)

ドキュメントとは?
IT業界では設計書、手順書、利用マニュアルなどを指す
設計書
業務の全体像、経緯
アーキテクチャやシステム間の連携
システム構成、インフラ構成が把握できる
手順書
メンテナンス手順
運用マニュアル
利用マニュアル
現代のシステムは複雑でドキュメントは必要不可欠

ドキュメント書いてますか？
アンケート
あなたの担当システム、ドキュメントはありますか？
そのドキュメント、更新されていますか？
なぜドキュメントを書かないのか
忙しい
面倒くさい
楽しくない

ドキュメント書いてますか？
このトラブルが解決したら、ドキュメントを書くんだ…
たまに耳にする
書いたためしがない

もしドキュメントが無かったら…?
ドキュメントが必要とされる場面
新しいメンバーが参画するとき
他のメンバーへの引き継ぎ時
システムのトラブルが発生したとき
もしこれらの場面でドキュメントが無かったら…?
あとでドキュメントを作ると高いコストを支払うことになる
更新されていないと余計な混乱が起きることがある

もしドキュメントが無かったら…?
よーく考えよう、ドキュメントは大事だよ

求められるドキュメントとは
必要とされるドキュメントの三つの特徴
内容が正確であること
簡単に書けること
誰もがいつでも参照・更新できること
分厚いドキュメントの山では変化に対応できない
必要なのはシンプルで変化に耐えうる軽量なドキュメント
Lightweight Documentation
ドキュメント作りを開発・運用サイクルに組み込む

テキストを図に変換するツール群
blockdiag：ブロック図、画面遷移図、フローチャート
seqdiag：シーケンス図
actdiag：アクティビティ図
nwdiag：ネットワーク図
blockdiagは定義ファイル(テキスト)から画像を生成する
レイアウトは自動的に行われる
多くの図形作成ツール(GUI ベース)と異なる考え方
細かく並べ替えたい人には向きません

世にある図作成ツール
世にある図を作るツール
Excel (方眼紙エディタ)
Visio, PowerPoint
Cacoo
特徴
WYSIWYG
マウスで要素を配置していく
好きな図が書けるけど、並び替えが大変

追加/削除が大変
ここに 1 画面追加

１.スキマを作る

２.不要な矢印を消す

３.図形を配置する

４.矢印を調整

ずれる

blockdiagシリーズと他のツール
Excel 他
レイアウトは手動で行う
好きなように並べることができる
並べないといけない
blockdiag
レイアウトは自動的に行われる
配置のことは考えなくて良い
好きなようには並べられない
多くの図形作成ツール(GUI ベース)と異なる考え方
見てくれよりも中身が重要だよね？

blockdiagの重要な周辺ツール「Interactive Shell」
Web ブラウザを利用してリアルタイムに図を作れる
SVG を利用しているため IE 非対応
高速に情報を共有するのに向いている
Interactive Shell で blockdiagを説明します
※ blockdiagは本来コマンドラインツールです

blockdiagの例
このテキストが…
{
トップページ -> ログイン -> マイページ;
トップページ -> 商品一覧 -> 商品詳細;
}

seqdiagの例
{
A => B => C;}

nwdiagの例
{
network { web01; web02; }
network { web01; web02; db01; }
}

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

サンプル図
blockdiag
画面遷移図: http://bit.ly/lZkszJ
ブロック図: http://bit.ly/kYpK6Y
フローチャート: http://bit.ly/m7fLsM
seqdiag
http://bit.ly/lwvEox
nwdiag
http://bit.ly/kR5tYF
http://bit.ly/qZvung(ciscoのフリー画像を使用)

blockdiagの周辺ツール
blockdiagの重要な周辺ツール「Interactive Shell」
Web ブラウザを利用してリアルタイムに図を作れる
SVG を利用しているため IE 非対応
高速に情報を共有するのに向いている
Interactive Shell を利用して、blockdiagをデモします

ドキュメンテーションツールとの連携
Sphinx
Redmine
Trac
moinmoin
Mediawiki
Web API
既存のドキュメントに対して簡単に図を埋め込める

今後の展開
新たな図、ドキュメントへの対応
システム構成図
ネットワーク図 (ラック、ハブ等の物理層)
画面定義書
他のツールと連携しての自動生成
ネットワーク通信のシーケンス図
ネットワーク図
プログラム構成図

#odstudyに望むもの

どんなドキュメントが欲しいのか
章立て・構成の共有と検討
現場の情報はさすがに共有できない
骨格だけでも共有できないだろうか
どんな図を書いているのか
私は blockdiagシリーズ等、ツール面でサポートします
なにが欲しいのかを教えて欲しい
開発は(ユーザの)ワガママドリブン
とりあえず要望や意見を挙げて欲しい

#odstudyへの提案(アイディア)
こんなものを考えてみてはどうでしょう
ドキュメントのテンプレート
手間暇のバランスを考えて、松竹梅とか?
ネットワーク系の図
物理配線
ラック図
仮想環境を踏まえたネットワーク図

まとめ
手軽にメンテナンスできるドキュメントのヒミツ
blockdiagシリーズを使いましょう
並び替えや位置調整に手間をかけない
図を作るのにスピードを与える
楽するためには知恵と経験が必要
#odstudyで話し合ってみてはどうだろうか
ツール面でサポートします。アイディアください
URL: http://blockdiag.com/
Twitter: @tk0miya #blockdiag
Google グループ: blockdiag-discuss

http://mistymagich.wordpress.com	61
http://webcache.googleusercontent.com	4
http://twitter.com	1

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

by Takeshi Komiya on Jul 22, 2011

Accessibility

Categories

Tags

Upload Details

Usage Rights

3 Embeds 66

Statistics

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