More Related Content Similar to sphinx + blockdiag で始めるドキュメント生活 2011/05 yokohama.pm (20) More from Takeshi Komiya (19) sphinx + blockdiag で始めるドキュメント生活 2011/05 yokohama.pm2. 自己紹介 小宮 健 (@tk0miya) 株式会社タイムインターメディア所属 技術者募集中してます! 普段は PHP, Python, Perl, Ruby などを書いています Sphinx-users の方から来ました 6. 誰のためのドキュメント? 2 種類のドキュメントが存在する 納品物としてのドキュメント (= お客さんのもの) 設計/運用のためのドキュメント (= 自分たちのもの) 足りないのは「設計/運用のドキュメント」 時間、コスト、ノウハウ不足で書けない トラブルや引き継ぎの時に必要だと気づく 喉元が過ぎて熱さを忘れちゃうことも多い 8. Lightweight なドキュメント ツールをうまく使う Sphinx、Wiki で書く ソースに埋め込む (POD, Javadocなど) やり方を変える テンプレートを使ってスタートダッシュする ドキュメントサンプル @ Sphinx-users 常に書き換える (Wiki 方式) 無理なく、楽しく、続けられるドキュメントであること 12. Sphinx の特徴(1) 読み書きしやすい reSTフォーマット 書きたいものがシンプルに書ける 様々な形式に変換できる make コマンド一発で変換できる make html, make pdf, make epub … レイアウトなどの余計なことに煩わされない 見栄えが整っていて気分がいい ページ間の相互リンク (自動索引、参照) 13. Sphinx の特徴(2) 強力なコードハイライト Perl, C++, Python などプログラムコード nginxの設定ファイルなど 拡張機能が豊富 graphviz, aafig, gnuplot, plantumlなどを組み込める ドキュメントが日本語化されている 豊富な利用実績 15. 他ツールとの比較(2) POD POD フォーマットで書く テキストでも perldoc経由でも HTML としても読みやすい モジュールのドキュメントによく使われる VCS を使えば複数人で編集できる Sphinx reSTフォーマットで書く テキストでも変換しても読みやすい アプリのドキュメントによく使われる VCS を使えば複数人で編集できる 16. 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/ 35. netdiagの例 このテキストが… diagram { network global { address = "210.x.x.x/24”; web01; web02; } network dmz { address = "172.x.x.x/24”; web01; web02; db01; db02; } } 43. 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