**************************************************************** Operation Document Model **************************************************************** .. meta:: :description: システム開発や運用現場にドキュメントはつきものである。しかし、ドキュメントを作る時間や更新する時間が取れない、わかりやすいドキュメントの作り方がわからない、折角書いたドキュメントの使いまわしが効かずに手間がかかっている、更にはそのドキュメントを作る価値や工数などが上層部からなかなか認めてもらえないなど悩みは尽きない。24時間365時間稼動を求められる運用現場においても、ドキュメント不足による属人化やスキルの偏在によるトラブルの多発および特定メンバーの異動や退職による事業継続性リスクが課題となっている。ここでは、運用ドキュメントの考え方や課題を整理した上で、 「手軽にスピーディに継続的に保守できるドキュメント」を実現するために必要な「情報の構造化」「再利用」「変更管理」 について検討したい。 :keywords: 運用ドキュメント, ドキュメント構造化 LastUpdated: |today| .. # LastUpdate: $IsoDate$ # Revision: $ShortRevision$ # Committer: $Author$ # Filename: $Basename$ # $Source$ - No Document, No Future. - Agile Documentation. - 個人的なメモの暫定置き場です。いずれ運用研究活動にマージしたい。 - 本稿は http://rsh.csh.sh//operation-document/ で公開しています。 ================================================================ 運用ドキュメントとは何か ================================================================ ---------------------------------------------------------------- 考察: 人はなぜドキュメントを書くのか ---------------------------------------------------------------- 目的1: 未来の自分への共有 - 備忘、過去の証跡 - 知識、経験の整理、外部化(ノート) - 行為の定型化 (手順書、チェックリスト) 目的2: 複数人での共有 - 備忘、過去の証跡 - 認識の共有、確認 - 知識の転送 - 定型化 (設計、実装、運用) 目的3: 不特定多数との共有 - オピニオン/ジャーナリズム - 普遍的な真理を後世に残す .. _expect-by-document: ---------------------------------------------------------------- 考察: ドキュメントが実現するものは何か ---------------------------------------------------------------- ドキュメントを書くことによって、以下の4つの効果が実現されると考えられる。 記録 (Level-0) (ドキュメント の本質的な基礎機能) 整理 (Level-1) 「書く」という行為により「整理」されていく効果。 .. note:: - 整理されたドキュメントは、自分もしくは他者に対してなんらかの価値を持ちはじめると考えられる。 - ただし、客観化を意識せず主観的に記述されたドキュメントは、他者には理解しずらいことが多い。 客観化 (Level-2) 「他者の閲覧を前提とした記述」をすることで、有形の成果物として「客観化」される効果。 脱属人化 (Level-3) 高度に「客観化」されることにより、地域(空間)や時代(時間)を越えてその知識や経験が共有されていく効果。 ---------------------------------------------------------------- 「運用ドキュメント」とは何か ---------------------------------------------------------------- .. glossary:: 運用ドキュメント 「運用業務に関連して、自分や他者に共有する目的で、書かれる文書」とここでは定義する。 その共有範囲は、各ドキュメントの目的によって異なる。 ================================================================ 運用ドキュメントの必要性 ================================================================ ---------------------------------------------------------------- 運用現場における典型的な声 (ドキュメント関連) ---------------------------------------------------------------- `Internet Week 2009 発表資料 `_ より (P9) - 業務が多岐に渡り、全てを把握することが困難になっている。 - 業務の設計思想が失われていて、すでにどうにもならない? - ドキュメントが整備されていない。あっても更新されていない。 - どんなドキュメントが必要なのかがわからない。書き方がわからない。 - 一部の人間にしかできない業務があり、業務が集中している。 - 属人化が進み、ノウハウの継承ができていない。 - 異動により現場が混乱することが多い。 ---------------------------------------------------------------- ドキュメントのない運用の弊害 ---------------------------------------------------------------- `ThinkIT 現場視点からの運用方法論 第3回 明日の運用現場のために - 運用フレームワークという視点 `_ より - ドキュメントのない作業は、運用現場自身でも正確な内容把握が難しいため、作業内容のブレやモレを生みやすく、ミスやトラブルの温床になりやすい。 - ドキュメントのない作業は、正確な業務引き継ぎが困難であり、メンバーの異動や退職により運用現場を混乱させるリスクが高い。ひいては事業の継続性にも影響しかねない。 - ドキュメントのない作業は、対外的な説明が難しく、（ユーザー視点では）存在しないことに近い。そのため評価されにくい。 - ドキュメントのない作業においては、その作業に必要なスキルやツールを、運用現場が的確に定義し、正確に相手に提示することが難しい。 .. note:: 「運用は忙しそうにしているけど、何やっているのかわからない」と言われてしまう。 ---------------------------------------------------------------- 運用ドキュメントが必要な理由 ---------------------------------------------------------------- 0.記録(Level-0)のために必要 自分達のやっていることを記録(証明)するために必要 1.整理(Level-1)のために必要 自分達のやっていることを知る&改善するために必要 2.客観化(Level-2)のために必要 自分達のやっていることの説明もしくは引き継ぎ、(自己・他者)評価のために必要 3.脱属人化(Level-3)のために必要 自分達のやっていることの安定化&永続化のために必要 .. image:: ./define/images/doc-purpose-level.png :width: 320 .. note:: 運用ドキュメントは、「自分達のやっていること」を自分達および他者と共有するために必要となる。 ---------------------------------------------------------------- 必要性が増していく運用ドキュメント ---------------------------------------------------------------- 「今現在は困っていないから」とは、言うものの.... 業務の複雑化、変化の激化 口頭で伝える(口伝)には限界を迎えている。(トラブル多発リスク) グローバリゼーション & 均質社会からの変化 空気を読むこと前提での業務は難しくなりつつある。(コミュニケーションの変質) 強み(ノウハウ)の無い現場はクラウド/オフショアに食われていく。 客観的なノウハウはドキュメントの上に積み上がっていく。 .. note:: - ドキュメントが無い事によるリスクが、かつてないほどに高まっている。 - 現場や自分達を守る・育てるために書く ================================================================ 考察: 運用ドキュメントの価値 ================================================================ ---------------------------------------------------------------- 運用ドキュメントの価値とは何か? ---------------------------------------------------------------- 一般的に「ドキュメント」と言われるものは非常に多種に渡り、その価値も多様であるが、運用ドキュメントについては、「共有する目的」で書かれる文書であることから、その価値は第一義的には「いかに使われたか」(利用価値)で評価することができると考えられる。 一方で、ドキュメントを提供する側では、そのドキュメントの作成維持に無限のリソースを使用することはできないため、そのドキュメントの提供に関わる費用対効果が問われることになる。 ---------------------------------------------------------------- 運用ドキュメントの利用価値 評価ベンチマーク ---------------------------------------------------------------- 各運用ドキュメントの利用価値は、「いかに使われるか」という観点から、下記の3つの指標で決まると考えられる。 1. 読者の範囲 - 水平方向: 社会的範囲 (特定現場 〜 不特定多数) - 垂直方向: 社会的地位 (専門層/経営層 〜 一般層) 2. 参照回数 3. 利用期間(寿命) ---------------------------------------------------------------- 運用ドキュメントの利用価値の源泉は何か? ---------------------------------------------------------------- 特定の運用現場におけるドキュメントのように読者の範囲を固定できる場合は、参照回数、利用期間の2つがドキュメント利用価値の重要な要素となる。 この参照回数、利用期間の2つに影響を与える以下の3要素が、該当読者に提供するドキュメントの利用価値の源泉と言える。 反復利用できること (可用性 Availability) 使いたい時に使える(反復利用できる)状態になってはじめて利用価値が生まれる - 参照回数による利用価値増 (直接影響) - 利用期間による利用価値増 内容が信頼できること (信頼性 Reliability) 内容の間違いが最小限である(最新を維持する)ことで利用価値(信頼)が高まる。 - 参照回数による利用価値増 - 利用期間による利用価値増 (直接影響) - 「間違い」には時間経過による変化で生じた「差分」も含まれる。 利用機会を増大できること (保守性 Serviceability) 再利用性を高め、ドキュメント数を増幅させることで、読者の利用機会を増大させることが可能となる。 - (間接的に) 参照回数による利用価値増 - (間接的に) 利用期間による利用価値増 - 信頼性維持工数を確保する上でも保守性が重要となる。 - 部品再利用することで維持工数の低減効果もある。 上記3要素は、直接間接的に参照回数、利用期間を増大させ、その運用ドキュメントの最終利用価値を増加させることに寄与する。 .. note:: - 繰り返し使われ、寿命が長いほどドキュメントの利用価値は高い。 - 利用価値(読み手の信頼)の維持には、継続的に差分更新を行い、常に最新である必要がある。 - 更新されない、繰り返し使われない運用ドキュメントは利用価値が低い。 ---------------------------------------------------------------- 運用ドキュメントの利用価値を低減させるもの ---------------------------------------------------------------- 可用性/信頼性/保守性の利用価値3要素が利用者の期待を満たせない場合、その運用ドキュメントについては直ちに陳腐化が始まり、「時間の経過により現実と乖離していく」という一種の経年劣化とともに、最終的な利用価値は極めてゼロに近くなっていく。 可用性低下による利用価値低減 使いたいときにドキュメントを利用できない。 - 所在: どこにあるかわからない。 - 真正: どれを使えばいいかわからない。 - 常時: 必要なときにアクセスできない。 信頼性低下による利用価値低減 ドキュメントが信頼できない。 - 誤り: 記述が間違っており信頼できない。 - 古い: 内容が古く現状と異なっており信頼できない。 - そもそも内容に利用価値が感じられない - 「整理」効果がない。 (Ex. 雑然と記述されただけである。) - 「客観化」効果がない。 (Ex. 整理されているが主観的である。) - 「脱属人化」効果がない。 (Ex. 客観化されているが、前提の明示化が不十分である。) 再利用性(保守性)低下による利用価値低減 ドキュメントの維持保守ができない。(提供機会の増大どころではない。) - 工数: ドキュメントを作成・更新する工数の確保ができない。 - 手間: 一単位あたりのドキュメント作成・更新工数が大きい。 - 手法: ドキュメントの構造化手法が作業者によって異なるため、他人の作ったドキュメントに手を入れにくい。 .. note:: - 時間の経過とともにドキュメントは経年劣化(陳腐化)していく。 - ドキュメント保守は、陳腐化との闘いである。 - 信頼低下や陳腐化したドキュメントは利用されなくなり、利用価値を失っていく。 .. IA2011 本論では、保守性に着目し、 - 手法 (分類、構造化) - 手法: ドキュメントの構造化手法が作業者によって異なるため、他人の作ったドキュメントに手を入れにくい。 - 工数 (作成維持工数の抑制) - 工数: ドキュメントを作成・更新する工数の確保ができない。 - 手間 (業務利便性向上の定性的効果) - 手間: 一単位あたりのドキュメント作成・更新工数が大きい。 について考察していく ---------------------------------------------------------------- 運用ドキュメントの提供価値 (費用対効果) ---------------------------------------------------------------- ドキュメントを提供する側では、反復利用、再利用性の高さと、陳腐化の早さに着目し、各運用ドキュメントの費用対効果(資産性、費用性)を評価することができると考えられる。 .. glossary:: 資産性ドキュメント その価値が時間の経過自体には影響されにくく、反復利用・部品再利用性の高いドキュメント (stock型) - 変更差分の継続更新により陳腐化回避を実現しているドキュメント - 「費用対効果」の「費用」は作成/維持工数 - 「費用対効果」の「効果」はドキュメント資産の形成/維持 費用性ドキュメント その価値が時間の経過とともに減少しやすく、反復利用されず、部品再利用性の低いドキュメント (flow型) - 差分更新の効果が低く、作成直後をピークに以後陳腐化していくドキュメント - 「費用対効果」の「費用」は作成/維持工数 - 「費用対効果」の「効果」 - 作成/維持工数が共通配賦(販管費)される場合: その価値の減衰が早いため資産/収益効果を説明するのが難しい。 - 作成/維持工数が直接配賦(売上原価)される場合: 間接的に収益効果として説明しやすい。(収益性ドキュメント) .. note:: - 資産性ドキュメントはコストセンターと言われがちな運用現場の産み出す唯一の有形資産 - 費用性ドキュメントに割く時間を減らし、資産性ドキュメントに割く時間を増やすべき時期が来ている。 - 現場や自分達を守る・育てるドキュメントにこそ工数を割き、高い資産性価値を形成すべき。 ================================================================ 運用ドキュメントの分類 (運用ドキュメント モデル) ================================================================ 運用現場におけるドキュメント群について、その目的や主要な利用者を基に標準モデルとして表現できるのではないか。(仮説) .. note:: 5W1H情報による運用作業ドキュメントモデル (2010年12月) - `ThinkIT 現場視点からの運用方法論 第3回 明日の運用現場のために - 運用フレームワークという視点 `_ より .. 作業定義書（5W文書） 各作業について、何を（what）、いつ（When）、どこで（where）、誰が（who）、なぜ（why）行うのかを明記した文書です。 主に、運用設計を行う時や、運用業務の分析／評価時に必要となるほか、メンバーのOJT時に各作業の意図を理解してもらう上で非常に重要な文書となるでしょう。中でも、why（なぜ）は文書化されていないと失われやすく、作業を形骸（けいがい）化させる原因となりえるので留意が必要です。 作業手順書（1H文書） 各作業について、どのように（How）行うのかを明記した文書です。 実際に作業を行う上で必須ともいえる重要な文書です。 更新されていない手順書は、トラブルを誘発するなどかえって有害となることもあるので、作業手順書の更新は最優先で行うなどの留意が必要です。 運用ドキュメントの分類 (書き手 + スコープ + 期待効果) (2011年11月) - (この記事です) 運用ドキュメントについては、その記述をする主体(書き手)、客体(対象のスコープ)、求められる効果の3つの軸により、分類(モデル化)することが可能と考えられる。 ---------------------------------------------------------------- 第一軸: ドキュメント主体(書き手)による分類 ---------------------------------------------------------------- そのドキュメントを生成する主体(書き手)によって「主観ドキュメント」か「客観ドキュメント」に分類する。 .. glossary:: 主観ドキュメント 人の手を介して作成維持され、その人の価値判断が含まれるドキュメント - その成果物の価値は個人への依存が高く、また工数が一定ではないため、その価値が工数の大小による影響を受けやすい。 客観ドキュメント 一定の規則性に基いてシステマティックに生成されるドキュメント - その成果物の価値とその生成のための工数は一定であることが期待される。 ---------------------------------------------------------------- 第二軸: ドキュメント客体(対象となるスコープ)による分類 ---------------------------------------------------------------- 次の3要素によりドキュメントの対象となるスコープを分類していく。 読者の範囲 (自分 / 特定の現場 / 不特定多数) ドキュメントの対象読者による分類 - 各運用ドキュメントの目的により求められる対象範囲は変わり、目的に沿った読者に対して合致した内容とすることで価値が高まる。 - 「運用ドキュメントの利用価値」ベンチマーク3指標の1つである。 対象時期の範囲 (過去 / 現在 / 未来 / 普遍) ドキュメントの対象時期による分類 - 運用ドキュメントにおいては、一般的に「現在」を対象とするものの価値が最も価値が高く、「過去」と「未来」については、現在から離れるほど価値が逓減していくと考えられる。 テーマモデル (状態(Status) / 変化(Change) / 活動(Activity)) :ref:`sca-analysis` に基づく、ドキュメントのテーマモデルによる分類 ---------------------------------------------------------------- 第三軸: 期待される効果による分類 ---------------------------------------------------------------- :ref:`expect-by-document` のレベルで分類していく。 - Level-0. 記録 - Level-1. 整理 - Level-2. 客観化 - Level-3. 脱属人化 .. note:: 一般的にレベル1の「記録」よりも高レベルの効果の方が価値が認識されやすい。 ---------------------------------------------------------------- 運用ドキュメントモデルに基づいた基本設計 ---------------------------------------------------------------- 運用ドキュメントの作成や継続的な維持管理のための工数を確保し、その費用対効果を経営層に説明する上で、ドキュメント設計時に、まず第一軸でドキュメント生成上の工数変化や継続性を想定し、更に第二軸、第三軸によりそのドキュメントに期待されるスコープや効果をあらかじめ明確にし、同じ工数でより高い評価(価値)が得られるためのドキュメント作成方針を事前に確定させておく意義は大きいだろう。 .. _sca-analysis: ======================================================================== SCA分析 (仮称) ======================================================================== .. note:: SCA分析 ドキュメントテーマの情報特性によるモデル (2011年11月公開) .. 2010年夏から2011秋まで、ひとりブレスト。 各ドキュメントのテーマは、 時間軸に対する位置関係により、時間軸の点である「活動」、時間軸上の一点における認識世界を示す「状態」、ある状態と他の状態の差分である「変化」の3種類のテーマに分類(テーマモデル)できると考えられる(SCAテーマモデル仮説)。 .. image:: ./define/images/theme-model.png .. _sca-circle: ---------------------------------------------------------------- SCA分析 3ステップサイクル (Status -> Activity -> Change) ---------------------------------------------------------------- SCA分析では、 各運用ドキュメントについて下記の3ステップサイクルにおける各局面をそれぞれ切り出したものと捉えている。 1. ある特定の「状態」を起点に「活動」が行なわれる 2. その「活動」の結果として新しい「状態」が生まれる 3. 活動前の「状態」と活動後の「状態」の差分として「変化」が生まれる。 Status(状態) ある領域の特定時における状態を切り出したものであり、時間軸に対して直交する。 - 「変化」「活動」の起点・終点となる最も重要なドキュメントテーマであり、常に参照されうる特性上反復・再利用性の高いドキュメントであることが求められる。 Activity (活動) 運用業務諸活動の原単位であり、個々の「活動」は時間軸上の点として表現される。 - 「活動」ドキュメントは反復作成されるドキュメントテーマだが、記述内容が該当活動に限定される特性上、再利用はしにくく、記録としての価値以外は陳腐化が早い。 Change(変化) 「状態」と「状態」の差分であり、時間軸に対して並行する。 - 「変化」は「活動」の蓄積により生まれると考えられ、主に「活動」に対する効果測定に用いられる。 - (但し、「変化させない」事が活動目的となる業務もありうることに留意が必要である)。 - 反復作成されるドキュメントテーマだが「変化」ドキュメント自体は期間に従い常に新規に作成されるものであり、再利用はしにくく、時間の経過とともに参照されなくなり陳腐化が進んでいくと考えられる。 .. note:: 想定される陳腐化の速度がゆるやかな順に SCA(Status Change Activity)分析と仮称する。 ---------------------------------------------------------------- 主観/客観によるテーマモデルの修正 ---------------------------------------------------------------- 実際のSCA分析においては、該当ドキュメントが主観ドキュメント(価値判断が含まれるもの)/客観ドキュメント(システマティックに生成されるもの)のどちらに属するかによって、いくつか定義と用語の修正を必要とする。 主観ドキュメント ******************************** 人手によって作成される「主観ドキュメント」では、下記定義の修正をする。 状態 (Status -> Define) その時点での状態に対する認識や定義 活動 (Activity) (主に)能動的な活動 変化 (Change) 能動的な活動の結果生じる変更差分 .. image:: ./define/images/theme-model-type-subjectivity.png 客観ドキュメント ******************************** システマティックに生成される「客観ドキュメント」では、下記定義の修正をする。 状態 (Status) その時点での状態そのもの 活動 (Activity -> Event) 受動的な事象 変化 (Change -> Difference) 何らか事象により受動的に生じる変化 .. image:: ./define/images/theme-model-type-objectivity.png ---------------------------------------------------------------- SCA分析 (主観/客観ドキュメント まとめ) ---------------------------------------------------------------- .. image:: ./define/images/theme-model-type.png ---------------------------------------------------------------- SCA分析と工数評価 ---------------------------------------------------------------- :term:`資産性ドキュメント` 、 :term:`費用性ドキュメント` という分類を実際に行なう場合、 資産性、費用性の判断基準を時間経過による価値への影響の有無大小で捉えていることから、各ドキュメントについて SCA分析 を行なうことでその判断をすることができる。 .. これら3つの類型は、それぞれに再利用性や陳腐化の速さで、費用対効果の観点から違う価値特性をもっている 状態 (Define / Status) - 反復・再利用性の高いドキュメント(資産性ドキュメント)。 - 「変化」「活動」の起点・終点となる最も重要なドキュメント - 何らかの形で売却できる場合「収益性」があると言える。 活動 (Activity / Event) - 反復作成されるが再利用はしにくい。(費用性ドキュメント) - コストが直接配賦されれば「収益性」があるが、共通配賦される場合は、作成自体が「運用コスト」と評価される。 変化 (Change / Different) - 反復作成されるが再利用はしにくい。(費用性ドキュメント) - 「運用の費用対効果」を最も説明しやすいドキュメントであり、その評価が運用現場のなんらかの利得に繋る場合は「収益性」があると考えることもできる。 - 「活動」の蓄積が変化を生む。 - [留意]「変化させない事」が重要とされる業務もある。 ---------------------------------------------------------------- 注力すべきドキュメントテーマ ---------------------------------------------------------------- 限られたリソースの中で効率良く運用ドキュメントの価値を維持拡大するためには、下記の3つの視点が重要になると考えられる。 1. いかに「活動」ドキュメントを効率良く低工数で作成するか。(費用性ドキュメントの抑制) 2. いかに「状態」ドキュメントを効率良く適正に維持拡大するか。(資産性ドキュメントの拡大) 3. いかに「活動」を効率よく実行し、「状態」を適切に把握し、効果測定としての「変化」ドキュメントを的確に作成するか。(収益性ドキュメントの拡大: 費用対効果の適正化) :ref:`SCA分析 3ステップサイクル ` により、運用業務においては、 - 1. 「活動」の起点となる「状態」を正確に把握しなければ的確な「活動」はできない - 2. 更に「活動」の結果を適切に反映した新しい「状態」の把握無しに、的確な「変化」を表現する事はできない と言うことができる。 更に一般的には、 - 3.的確な「変化」の表現無しに「活動」の結果を第三者に客観的評価させることは難しい と言うこともできるだろう。 .. note:: - "状態" なくして的確な "活動" はできず、"変化" なくして "活動" は評価できない。 - いかに "活動" を効率よくし、"変化" を産むか。 - 新旧の "状態" はそのための基盤 ================================================================ ドキュメントの構造化 ================================================================ ドキュメントの効率的な維持管理の観点から、ドキュメントの構造化については今後非常に重要になってくると考えられる。 ---------------------------------------------------------------- 構造化とは ---------------------------------------------------------------- 構造化 本稿では「ばらばらになっているものを、一定の基準に従い論理立てて整理すること」と定義する。 ---------------------------------------------------------------- ドキュメント構造化の基本3要素 ---------------------------------------------------------------- 一般的に「ドキュメントの構造化」においては、下記の3つの「構造化の基本要素」が利用されている。 文章ブロック単位での意味付け (見出し) 文章ブロックに「見出し」を付けることは、その文書全体におけるその文章ブロックの「責務の明確化」を行なうことであり、最も基本的な構造化作業である。 読み手が認識しやすい位置への文章ブロックの格納 (目次) ドキュメントの「目次」を作成することは、そのドキュメント全体をツリー構造で表現することであり、ドキュメントの全体設計という最も重要な構造化作業である。 文章ブロック間の関係付け (クロスリファレンス) ドキュメントに「クロスリファレンス」を作成することは、ツリー構造で表現された文書内部において、関係のある文章ブロック間にネットワーク構造を構築することであり、ネットワークの集中するところにそのドキュメントの価値的な比重があることを表現する付加価値の高い構造化作業と考えられる。 .. note:: ドキュメント構造化における「文章ブロック」は、文書ツリー構造における末端ノードとなることから、本稿では以下「情報ノード」と表現する。 これら「ドキュメント構造化の基本3要素」に、最も基礎となる情報ノード群である 5W +1W を追加したものが、運用ドキュメントにおける一般的な共通構造である。 - 「What(タイトル)」 - 「Why(記述目的)」 - 「When(作成日、 記述対象時制:過去/現在/未来)」 - 「Where(記述対象空間)」 - 「Who(著者)」 - 「Whom(想定読者) ---------------------------------------------------------------- テーマモデル別のドキュメント構造化 ---------------------------------------------------------------- 運用ドキュメントにおいては、「目次」の大見出しのレベルで SCA分析 によるテーマモデル毎の構造が表現されると考えられる。 「状態」の構造 その対象が「時間軸上の一点における認識世界を示す」という特性上、森羅万象に及びかねないため、その構造モデルは検討できていないのが現状である。 「活動」の構造 - 「活動」の主体(誰が)に関する記述 - 想定している活動前「状態」(何を)に関する記述 - 想定される活動後「状態」(どうするために)に関する記述 - 「活動」内容 (いつ、どうする)に関する記述 - 実際の活動後「状態」(どうなった)に関する記述 「変化」の構造 - 変化前の「状態」に関する記述 - 変化後の「状態」に関する記述 - 差分(「変化」そのもの)に関する記述 - 「変化」に影響を与えた「活動」に関する記述 ---------------------------------------------------------------- ドキュメント構造化の効果 ---------------------------------------------------------------- 構造化による効果は以下の3点が考えられる。 効果1. 中長期的には書き手がドキュメントを書きやすくなる。 逆説的な説明になるが、構造化ドキュメントを記述するには、そのドキュメント対象を構造化して捉えなおさなければならず、構造化して捉えなおした対象を構造的に記述することは容易になると考えられる。 .. note:: 見出し付け時に各情報ノードの責務を明確化することにより重複を回避しやすくなる、情報ノードを追加時などの目次の更新において内容の過不足を把握する機会が増える、などの効果が考えられる。 効果2. 読み手がドキュメントを読みやすくなる。 目次のわかりやすい本は一般的に読みやすいと言われているが、適切に構造化されたドキュメントはドキュメント対象を構造的に理解することを可能とし、時間が限られる読み手にとって対象の取捨選択を容易にする効果がある。 .. note:: 取捨選択が容易であることは、利用工数の削減をもたらし、反復利用を促進し、利用機会の増大に繋ると考えられる。 効果3. 主観ドキュメントと客観ドキュメントのセグメントを明確に分離することが可能になる。 構造化されたドキュメントでは、全てを人が手で記述する必要がある主観ドキュメントのセグメントとシステマティックに生成されるべき客観ドキュメントのセグメントを明確に分離することが可能になると考えられる。 .. note:: - 運用ドキュメントの今後を考える上で、作成工数の抑制と効率的な維持管理を実現するための「システマティックなドキュメント生成」という視点は重要になる。 - セマンティック技術の再評価、情報の「マッシュアップ」技法など、IT技術によるIT技術現場のためのドキュメント技術の実践拡大が今後強く期待される。 以上、構造化による想定効果について述べてきたが、書き手にとって最も大きい効果は、構造化されたドキュメントは、他者への引き継ぎが比較的容易と考えられる点かもしれない。 ---------------------------------------------------------------- まとめ: ドキュメント構造化(例) ---------------------------------------------------------------- - 共通構造 - 情報ノード - 「What(タイトル)」 - 「Why(目的)」 - 「When(作成日、 記述対象時制:過去/現在/未来)」 - 「Where(対象空間)」 - 「Who(著者)」 - 「Whom(想定読者) - 見出し - 目次 - クロスリファレンス - 状態の情報ノード - 森羅万象 千差万別 - 外見主義 カプセル化 - 活動の情報ノード - 「活動」の構造 - 「活動」の主体(誰が)に関する記述 - 想定している活動前「状態」(何を)に関する記述 - 想定される活動後「状態」(どうするために)に関する記述 - 「活動」内容 (いつ、どうする)に関する記述 - 実際の活動後「状態」(どうなった)に関する記述 - 変化の情報ノード - 変化前の「状態」に関する記述 - 変化後の「状態」に関する記述 - 差分(「変化」そのもの)に関する記述 - 「変化」に影響を与えた「活動」に関する記述 ================================================================ 運用ドキュメントの作成維持工数抑制のために必要なもの ================================================================ 陳腐化との関係 - 常に最新 - 保守性 (reST) - 再利用性 - 半自動化 ================================================================ SCA分析 & 構造化 による運用ドキュメントの利便性 ================================================================ - 利用者の利便性 - 提供者の利便性 - 経営層の利便性 ================================================================ 運用ドキュメントをどう作成するか? ================================================================ - 基本設計 (プランニング) - 機能設計 (材料収集) - 詳細設計 (構造設計) - コーディング (執筆) - テスト (推敲) - 完成 (参考: 佐藤 健 「SE のための「構造化」文書作成の技術 (技術評論社 2008年) P44) ================================================================ 運用ドキュメントをどう維持管理するか? ================================================================ ---------------------------------------------------------------- 運用ドキュメントのライフサイクル ---------------------------------------------------------------- 運用ドキュメントは「完成したら終わり」ではない。 むしろ完成してからがスタート。(使いながら作る事も珍しくない) - 更新や廃止など、ライフサイクルを意識した継続的な維持管理が必要となる。 「ライフサイクル」には「お葬式」も重要 ドキュメントの廃止が明示的に行なわれることは少ない。 - 不要なドキュメントが廃止されないことで、無用のトラブルを生じたり、全体の保守性を下げ無駄な保守工数がかかる可能性がある。 定期的な棚卸は必須 廃止すべきドキュメントや、更新されていないドキュメントを洗い出す「定期的な棚卸し」が「ドキュメントのライフサイクル」では重要となる。 ---------------------------------------------------------------- 各運用ドキュメントに対するポリシーレベル ---------------------------------------------------------------- `Internet Week 2009 発表資料 `_ より (P89) Level-0 - 管理しない (個人任せ) Level-1 - 台帳管理 (リスト化) Level-2 - バージョン管理/検索機能 Level-3 - 分散協調管理 (集中管理は破綻するという仮説より) - 当時はイメージでしかなかったが、Mercurial + Sphinx で実現できそうな気がしてきた。 ================================================================ 運用ドキュメント システム モデル ================================================================ ---------------------------------------------------------------- 必要な要素 ---------------------------------------------------------------- - ドキュメントのメンテナンス簡易化 - ドキュメントの再利用、構造化、パーツ化 ---------------------------------------------------------------- 分散ドキュメントシステム 仮説 ---------------------------------------------------------------- .. image:: ./define/images/document-system-overview.png input (reST wiki (仮称)) - 誰でも入力できること。 - システム(UNIX)のアカウント/スキルが不要であること。 - アウトプットをイメージできると嬉しい。 - format processor のスタイルシートを呼び込むとか。 repository ( `Mercurial `_ ) - バージョン管理できる。 - 過去に戻せる。 - 過去との差分がわかる。 - 履歴を失なわない。 - 複数人で無理なくメンテナンスできる。 - キーワード置換ができる(gitはできない)。 - reST wiki ユーザから隠蔽(存在を意識しない)できると嬉しい。 - システム(UNIX シェル)のアカウント/スキルが不要だと嬉しい。 - ドキュメントのブランチ/マージによる多面利用化(公開版/内部版の並行更新など)が可能らしい Bug Tracking System (`Redmine `_ ) - リポジトリ連携機能により、チケット駆動ドキュメント管理(?)が実現 - 変更点(4W1H)はバージョン管理システムに残るが、そこに残りにくい意図やきっかけなど(Why)はチケットシステムに残る可能性が高い(かも)。 format processor ( `Sphinx `_ ) - マスタデータを各種フォーマットに簡単に変換できる。 - HTMLに変換できる。(作業担当者 閲覧用 / RESTfulによる所在固定化) - PDF/pptに変換できる。(ミーティングや成果物用) - ePubに変換できる。(モバイルパッド化は時代の流れ?) - reST で UML を扱えると、ものすごく嬉しい。( `blockdiag `_ ) - 状態遷移図が記述できる (分析 / フロー概要図) - オブジェクト図ができると嬉しい (分析 / フロー概要図) - アクティビティ図が記述できると嬉しい (設計 / 業務フロー詳細/マスター) - 配置図が記述できると嬉しい (システム構成図) - ロバストネス図が記述できると嬉しい (これは書くのも大変か?) - 日本語に完全対応だと非常に嬉しい。 - reST wiki ユーザから隠蔽(存在を意識しない)できると嬉しい。 ---------------------------------------------------------------- サンプル事例 (このページ自体) ---------------------------------------------------------------- input - vim + ターミナル で編集 ( `このページのソース文書 <./_sources/index.txt>`_ ) repository - Mercurial を利用 (キーワード置換でページトップに更新日を表示) - リモートリポジトリでの作業 - (最初だけ) mkdir ${rep_dir} - (最初だけ) cd ${rep_dir}; hg init - 編集側での作業 - (最初だけ) mkdir ${work_dir} - (最初だけ) cd ${work_dir}; hg init - (最初だけ) ${work_dir}/.hg/hgrc の編集 - hg add - hg commit - hg push - 公開サーバ側での作業 - (最初だけ) mkdir ${work_dir} - (最初だけ) cd ${work_dir}; hg init - (最初だけ) ${work dir}/.hg/hgrc の編集 - (最初だけ) hg clone - hg pull - hg update format processor - Sphinx を利用して HTML 出力 - 編集側で事前実行、確認 - 公開サーバ側での作業 - sphinx-build -b html ${work_dir} ${public_dir} ================================================================ Sphinx 考察 ================================================================ ---------------------------------------------------------------- 運用ドキュメントに求められるもの ---------------------------------------------------------------- 「簡単に」書けて「誰でも」使える「正確な」ドキュメントが求められる。 - 正確性 (正確なドキュメント） - 内容が論理的に正確であること (論理的正確性) - 内容が最新のものであること (時間的正確性) - 文書内の参照関係が正確であること (構造的正確性) - 容易性 (簡単に書けるドキュメント) - その気になったときに簡単に書けること (着手の容易性) - 書く事に集中できること (記述の容易性) - 一度書いた文書を使いまわしできること (再利用の容易性) - 継続性 (誰でも使えるドキュメント) - 置き場を誰でも知っていること (閲覧の継続性) - 更新方法を誰でも知っていること (更新方法の継続性) - 誰が更新しても良いこと (更新者の継続性) ---------------------------------------------------------------- 運用ドキュメントに Sphinx がもたらす(かもしれない)もの ---------------------------------------------------------------- 「簡単に」書けて「誰でも」書ける「正確な」ドキュメントを Sphinx がもたらす(かもしれない) - 正確性 (正確なドキュメント） - 論理的正確性: 構造化文書により、比較的発見しやすい? - 時間的正確性: 容易性により、比較的実現しやすい - 構造的正確性: パースチェックでデッドリンクなどを発見しやすい - 容易性 (簡単に書けるドキュメント) - 着手の容易性: テキスト文書 - 記述の容易性: reST - 再利用の容易性: make一発で多フォーマット & include/replace - 継続性 (誰でも書けるドキュメント) - 閲覧の継続性: Web共有など - 更新方法の継続性: reSTで書いてmake一発 - 更新者の継続性: バージョン管理システムなどの利用により実現可能 .. ---------------------------------------------------------------- .. 運用ドキュメントの陳腐化を防ぐために .. ---------------------------------------------------------------- .. - 陳腐化しないドキュメントとは .. - より現在の 状態 に近いものに価値がある ================================================================ ToDo ================================================================ - 「分散ドキュメントシステム 仮説」の図が画像なのはマケのような気がする。blockdiag で書き換える。 .. toctree:: :hidden: ./define/index ./change/index ./activity/index