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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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/

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

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

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

Excel 方眼紙時代の思い出

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

１.スキマを作る

２.図形を置く
３.矢印を調整

苦労その２：ずれる

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

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

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

blockdiag の例
こうなる

seqdiagの例
diagram {
browser => server;
}

seqdiag の例
こうなる

netdiagの例
diagram {
network global {
address = "210.x.x.x/24”;
web01; web02;
}
network dmz {
address = "172.x.x.x/24”;
web01; web02; db01; db02;
}
}

netdiag の例
こうなる

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

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

そのほかの装飾
ノードのグルーピング
遷移の説明文 (短め)

ノードの shape 属性を指定する
node1 [shape = “roundedbox”]
基本系

フローチャート系

その他

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

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

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

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

http://labs.timedia.co.jp	1910
http://bellonieta.net	235
url_unknown	24
http://www.slideshare.net	22
http://infra.rrdtool.net	11
http://localhost	9
http://webcache.googleusercontent.com	9
http://labs-timedia.sakura.ne.jp	2
http://twitter.com	1
https://twitter.com	1
http://s.deeeki.com	1
http://flavors.me	1
http://207.46.192.232	1

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

by Takeshi Komiya on May 13, 2011

Accessibility

Categories

Tags

Upload Details

Usage Rights

13 Embeds 2,227

Statistics

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