reSTudy ～ STudy group about reST ～

波田野 裕一

（reSTudy / 日本UNIXユーザ会)PyConJP 2011 / 2011-08-27

abstruct

reSTructured Text (reST) によるドキュメントサンプルをまとめる活動を行う、reSTudyについて紹介します。 !

活動の成果(?)などを紹介します。

おまえダレよ

ADSLキャリアでISP運用

小規模ISPの立ち上げ支援

官庁小規模システムの運用/Close

ASPでの運用設計PPyytthhoonn

全く書けません

最近

運用業務モデリングが趣味に

週末reST ドキュメント書いてばかりで、奥さんを嘆かせている

「運用の暗い話」ばかり得意に

運用の方から来ました

少し語らせてください

夢悪

「運用は何をやっているのか よくわからない」

とおっしゃる方がいます、が

お題

「やっている方もよくわかってないんですよ」、と

答え

までは、言えませんが、なんだかうまく説明できない。

ドキュメントのない作業は 「業務が存在しない」に等しい

ミスが多発

ドキュメントが無いと

異動で混乱運用でカバー

運用現場の制御不能状態を加速する

運用でカバー運用でカバー運用でカバー運用でカバー

理想は

No Document, No Operation.

http://thinkit.co.jp/

運用でカバー

クラウドに吸い込まれる運用現場

尖ったモノを持つ「攻める」運用現場

変化に柔軟に対応高度な専門性短納期/スピード 費用対効果が明確スケーラビリティ スティッキー

一般的な専門性 硬直的意思決定に時間 どんぶり勘定高コスト体質 非合理的

二極化する運用現場

5. 運用設計の諸要素

「運用基盤」3要素

✓ まずは作業内容を的確に表現したドキュメントがあることが大前提 !

✓ それではじめて作業内容に必要なスキル(教育内容)が明確になる。

!✓ 前提となる作業とスキルが明確になって、はじめてツールの話ができる。

ドキュメントスキル (教育)ツール

運用基盤とは

運用現場における典型的な声 (1/3)

✓ 業務が多岐に渡り、全てを把握することが困難になっている。

✓ ドキュメントが整備されていない。あっても更新されていない。

✓ どんなドキュメントが必要なのかがわからない。書き方がわからない。

✓ 一部の人間にしかできない業務があり、業務が集中している。

✓ 属人化が進み、ノウハウの継承ができていない。

✓ 異動により現場が混乱することが多い。

ドキュメントを作ろう

It's 業務資産!

運用ドキュメントが必要な理由

‣ ドキュメントのない作業は、運用現場自身でも正確な内容把握が難しいため、作業内容のブレやモレを生みやすく、ミスやトラブルの温床になりやすい。

‣ ドキュメントのない作業は、正確な業務引き継ぎが困難であり、メンバーの>異動や退職により運用現場を混乱させるリスクが高い。

‣ ドキュメントのない作業は、対外的な説明が難しく、（ユーザー視点では）存在しないことに近い。そのため評価されにくい。

‣ ドキュメントのない作業においては、その作業に必要なスキルやツールを、運用現場が的確に定義し、正確に相手に提示することが難しい。

運用ドキュメントに求められるもの

「簡単に」「誰でも」書ける「正確な」ドキュメントが求められる。 !!* 正確性 (正確なドキュメント） ! * 内容が論理的に正確であること (論理的正確性) * 内容が最新のものであること (時間的正確性) * 文書内の参照関係が正確であること (構造的正確性) !* 容易性 (簡単に書けるドキュメント) ! * その気になったときに簡単に書けること (着手の容易性) * 書く事に集中できること (記述の容易性) * 一度書いた文書を使いまわしできること (再利用の容易性) !* 継続性 (誰でも書けるドキュメント) ! * 置き場を誰でも知っていること (閲覧の継続性) * 更新方法を誰でも知っていること (更新方法の継続性) * 誰が更新しても良い (更新者の継続性)

未来へ進もう

現

今年は運用ドキュメントが熱い

2010年10月 OSC2011 Tokyo/Fall

2010年11月 手順書友の会 発足 (JANOG系)

2010年12月 jus勉強会

ドキュメントを作りたくなる魔法のツール

Sphinx

2011年 6月 odstudy 発足 Operation & Documentation

(渋川さん、清水川さん、山口さん)

道具もそろってきたいいバージョン管理システム

Mercurial

手順書のための構造化言語 構造化記法 reST + ドキュメントプロセッサ Sphinx

手順書管理媒体 バグトラッキングシステム Redmine リポジトリ連携 + ReSTfulAPI

blockdiagシリーズ (#世界の小宮さん)

次はこれだ

✓ 業務が多岐に渡り、全てを把握することが困難になっている。

✓ ドキュメントが整備されていない。あっても更新されていない。

✓ どんなドキュメントが必要なのかがわからない。書き方がわからない。

✓ 一部の人間にしかできない業務があり、業務が集中している。

✓ 属人化が進み、ノウハウの継承ができていない。

✓ 異動により現場が混乱することが多い。

あるあるSphinx

‣ Sphinx イイネ!

‣ とりあえず、はじめる。それもわるくはない。 ‣ しかし、後で知るとガーンとなることも多い。 ‣ ごりごりテーブル書いていた -> list-table

‣ ごりごり内部リンク書いていた ->クロスリファレンス

‣ リストで注意書き書いていた -> note & warnings

‣ だったら先に知っておきたいことを押えておくのが得策

‣ よかろう、それが re(ry

あるあるdocumentation

‣ 作り方はわかった、じゃ次は「何をどう作るか」、だ。

‣ ドキュメントって、必要必要と言う割にテンプレートがばらばら。

‣ うまく汎用的なテンプレートがあると嬉しいよね。

‣ テンプレートや知見、悩み相談みたいな場が欲しい。

‣ よかろう、それが re(ry

ドキュメントを作ろう

Let's reSTudy!

ここからはreSTドキュメントで.....