やさしい手順書の書き方

はじめに

• この記事は 富士通クラウドテクノロジーズ Advent Calendar 2020 の22日目の記事です。

• この記事は 富士通クラウドテクノロジーズ Advent Calendar 2020 の22日目の記事にはしませんでした。
  

概要

• この記事では、手順書の書き方について私見をまとめます。
  • 実際のところ、こういうことをまとめてメンバーとすり合わせたいとずっと思ってたのですができてなかったので、
    カレンダードリブンでえいやでまとめることにしました

---

背景

• 2020年3Q から、担務が多くなりチームが進める計画や作業を全体的に見る機会が増えました
  • 私はニフクラのネットワークチームに属しており、
    特にネットワーク機器まわりの設計/構築/運用/保守 を主たる業務範囲としています
• ネットワーク機器の運用について、運用自動化というキーワードはもう目新しいものではありません。
  • 所属するチームでも、私が入社する約6年前には既に順次着手を始めており、
    特にここ数年の間にはチームメンバーの強い推進によって格段に進んでいます。
    • この取り組みの内容については別途まとめたいところではありますが、
      次の機会、他のメンバーに水を向ける形としたいと思います
• 一方で、チームが日頃進める作業のうち、人が手動で行う作業もまだ残っています。
  • 割合で示すべきではありますが、完全にツールにお任せできる作業は数例であり、
    まだ大半が人の作業を必要としています
    • ここでいう作業は機器に対するconfig 編集を指すものとしますが、
      チームが自動化対象にしているのは作業のチケット化やログ管理、config 管理も対象としており、
      作業全体としての効率化は数年前より格段に進んでいます
  • この原因について、機器・機種・OS・情報管理・体制等様々な点がありこの話題でも一記事書けますが、
    この記事のスコープには含めないものとします。

定義

• この記事では、手順書を以下と定義します
  • ある目的を達成するために、担当者が機器やサーバ、または管理資料、あるいは関係者に対し行う動作処理を一連に記載したテキストや図等資料
• 多くの例に漏れず、チームが実施する作業について現在は以下のフローで下に進む形で承認経路が存在し、手順のレビューを行っています
  • 作業者
    • 手順書を記載する
    • 作業を行う
  • ダブルチェック者
    • 作業者の記載した手順書をレビューし必要があれば問題点を指摘する
    • 作業実施をダブルチェックする
  • リーダー
    • ダブルチェック者がレビューした手順書をレビューし必要があれば問題点を指摘する。問題が無ければ承認する
    • 筆者はここの立ち位置です
  • マネージャー
    • リーダーが承認した手順書をレビューし必要があれば問題点を指摘する。問題が無ければ承認する
    • 作業完了を承認する
• つまり、私が所属するチームでは基本的に、手順書の筆者と作業者は一致します。
  別チーム・別企業の場合ですと手順書作成者と、作業者（いわゆるオペレータ）が分かれていることも多いと思いますが、そうなってはいません。

本文

• 手順書を書く人が一番に、常に意識してほしいのは、人間は基本的に無能であり、さらに物事を簡単に忘れる生き物だということです。
  • 見た目で内容を判断し、細かいところまでいちいち読みません。
    • つまりこの記事も読みにくいのであまり読まれないことでしょう、チーム向けにはパワポでまとめたいなぁと思い続けてもう3Q が終わる
    • 見た目 にいろいろ書きます
  • 作業時には書いてあることを達成することに集中し、書いていないことに気を回すことは難しいです
    • 書いていないことに思いを寄せないばかりか、手順書を書いたはずのあなたでさえなぜその手番を書いたか忘れてしまいます。明日のあなたは別の人です
    • 内容の完全性 に書きます
• 次に大事なのは、手順書を書く目的は、作業を達成することではないということです。
  手順書を書く目的は、作業のドキュメント化・アーカイブ化です。
  • ドキュメント化
  • アーカイブ化
• 上記に比べてそこまで大事でないのは、手順が正しいことです。
  でも正しくないとレビューが通らないので大事です。
  • 手順の正しさ

見た目

見た目: 見出しを適切に

• 作業計画は構造的に組み立てられるものであるため、手順書も必然的に構造的になるはずです。
• どんな手順でも以下は書かれているべきであり、特に前例がない作業、一度しか実施されないであろう手順、トラブル等緊急対応の手順書では背景や目的がより詳しく書かれているべきです。

## 概要
### 背景・前提
### 目的・完了の定義
## 事前作業
## 作業
## 事後作業

見た目: 誤字脱字

• 誤字脱字については、コマンドのそれで無い限り、大抵は作業実施に問題ありません。

• ただし、誤字脱字は手順書の信頼性そのものを大きく損ないます。
  なぜならば、誤字脱字の存在は以下を懸念させます。

  • 手順書が読み直しされていないこと
  • コマンド等、致命的な部分で誤字脱字が混入している恐れ
  • 手順書筆者の能力・信頼性

• また、誤字脱字の存在を作業中に気づいた場合、本来必要のない部分で注意を引くこととなり、
  集中力を失わせる原因となります

• 特にレビュアーは、誤字脱字を指摘すること自体はレビューの本質でないことに留意しなくてはなりません。

  • 問題なのは、誤字脱字以外に重要なミスが存在している[可能性がある/可能性を想起させる]ことです。
    • 句読点が抜けているだとか、日本語（現在のメンバーは日本語ネイティブのみです）的に正しくないことを指摘することも本質でない
    • 繰り返しですが、レビュアーは、誤字脱字を見つけることがレビューではないことを念頭に置く必要があります。一方で発見した場合、レビューの警戒度を上げるべきではあります

• この記事でも誤字脱字等には気をつけているつもりですが、もしあれば刺してください

  • ちなみにこの記事に1カ所だけ、意図的に誤字を含めています。見つけた人はSlackかTwitterで教えてください。刺しに行きます

見た目: 何を読ませるか

• この記事の内容に同意してもらうかどうかはともかく、完璧な手順書を書こうとするとどうしても文字量は肥大化します。文章は冗長になります。
  • 物語を書くことと同様に、手順書の読者にはどこに集中させ、どこで気を抜かせるかを考えて書くのはどうでしょうか。
  • 特にリスクポイントの手番は、他の部分より目立たせて警戒を引くことが重要です。
  • その方法としては様々あると思いますが、チームで統一されているとよりよいと思います。
    • ちなみに色を分けることは一つの手段ですが、モニタ環境は人それぞれであることや、読者が色覚異常であることを考慮して、色で全てを区別することは避けるべきです。
      （通常部分が黒字で、重要部分が赤字というのは最低の色分けです）
• 説明文とコマンドは明確に見た目を変えるべきです。

コマンドはコードブロックを使うことがいいと思います。

• 長い手順の場合には、

  フェーズごとや機器ごとでDetailを用いて折りたたんでみると読みやすくなるかもしれません。

  見た目: ストーリーは上から下に

  • 手順書は基本的に上から下に読み進められるべきであり、分岐があるのは好ましくありません。
    • あるいは、実施しないことは書かれないべきです
    • 分岐するのは、切り戻しポイントのみであることが理想です。
      • なぜならば、手順を上に下に行ったり来たりすることで、可読性が落ち、
        さらには進行状況を見失い重要な手番を飛ばすリスクが多くなるためです。

  見た目: 図表を用いる

  • 特にネットワークの話をするときに図表は必要不可欠です。
    その作業が汎用的なものでなければ、構成図はあるべきです。

  内容の完全性

  • 手順書には全てが記載されているべきです。

  ---

  • 手順書には関連すること全てが記載されているべきです。記載されていないことは考慮されていないことであるとレビュアーは判断しますし、するべきです。

    • 例えば、以下のようなことでも手順書に記載されるべきです
      • "作業前に○○さんに連絡する"
      • 管理資料を忘れずに更新する
      • この作業が終わらないとあの作業ができない、またはその逆
    • なぜならば、手順書を書いた人間と作業者は一致しない可能性があるためです。
      • 特に手順書が数ヶ月・数年後に参照された場合、このあたりの問題点は刺さります

  • 手順書の口頭説明や、読み合わせは効果的に

    • 一つの手順書について会話しながら認識合わせすることは、
      作業理解のためには非常に効果的です。ただし、表裏一体です。
    • 口頭での認識合わせにおいて、しばしば手順上の問題点が発覚されたり、疑問が出てくることがあります。
      会話しながらなのですぐに意思疎通しその場の関係者内では解決したとしても、その事実と結果は手順書に書かれるべきです。
      • 問題点があった・疑問が出た事実を履歴として残すべきであるため
      • ひとりが持った疑問点は同様に他のメンバーも疑問に持つであろうため

  • 主語ははっきりと

    • 複数チーム・複数社との間で作業する場合、誰が何をするのかは明確に書かれているべきです。
    • 特に確認をするのは誰なのか、切り戻す判断をするのは誰なのか正しく定義することで、有事の際の行動が早くなります。

  • "確認" という言葉に気をつける

    • 作業は確認の繰り返しです。
      つまり"確認" することは当然であり、さらに以下を気をつける必要があります

  ! よくない例
  
    # show ip route
    
    # ip route [xxxx/xx] [xxxx]
    ! 疎通を確認する
  
  ----
  
  - どうやって? ping? traceroute? 
  - どこから? 実機から? サーバから? ユーザがするの?
  - 想定は?　疎通がとれることが正? 
  
  - (リスクある部分の場合、確認した結果が期待する内容に沿わない場合も書いた方がいい)
  

  • 切り戻しと切り戻し観点
    • 作業において想定外はつきもので、その際には作業を切り戻す判断をすることがあります。
    • 切り戻しに備え切り戻し手順を用意することは重要ですが、それよりも大事なのは切り戻し観点を定義することです。

  ドキュメント化

  • 手順書を書くことで、他人に理解させレビューさせることができます。

    • 従って、読者想定は作業者ではなく、作業者以外の人間です。
      つまり、手順書筆者だけにわかる表現や、省略はあってはいけません

  • さらに言えば、作業実施をするのも手順書筆者とは限りません。

    • 手順作成者と作業者が一致する場合、どうしても書く手順書が自分のやることメモになりがちですが、自分以外の人が読んでもわからない手順書は本当にメモです。
    • さらに言えば、明日の自分は他人ですので、明日の自分にわからないことを書いてはいけません

  アーカイブ化

  • 手順書を残すことで、作業事後の追跡や、手順の再利用が可能になります。
    • 従って、手順書は後から読まれることを意識して書かれるべきであり、
      コンテキスト性はなくすか、明記されているべきです。
  • ログは、全て適切に残されているべきです。
    • ログを取得したこと、ログを保存する場所、ログの内容は後からわかるよう手順書で定義されているべきであり、さらにチーム内で統一されていることが理想です。
  • 修正は大事だが履歴を残しましょう
    • 手順書はレビューされるため、結果によって手順の修正が入ることもあります。
      この修正履歴も重要です。
      - レビューが適切に行われ、これによって修正改善されたという履歴は作業の品質管理において非常に重要です。
      - 上述の通り、口頭での会話やSlack 等のツールでレビュアーと認識あわせをすることは非常に有効ですが、結果を履歴として残すことが重要です
  • 数年後に読まれることを念頭に置きましょう
    • その作業が前例がなく、また複数回も実施する作業でないと思われる場合、手順書は特に濃密に書くべきです。
    • なぜならば、一度やることになったその作業は例え稀だとしても、確実に将来再度実施されることが予想され、その際にはこの手順書が絶対に参照されるためです。
    • 従ってコンテキスト性はできるだけ排除し、作業を実施することになった背景や前提は特に詳しく記載するべきです。
  • コマンドを省略しないこと
    • 多くのネットワーク機器は、コマンドを一部省略しても省略したまま実行できます。
    • 以下はLinux OS(のzsh) の例ですが、tab補完で一意にコマンドが決定できる部分まで入力できていたとしても、
      コマンドは完全に入力されていなければ実行できません

  % touc test
  zsh: command not found: touc
  % touch test
  % 
  

  • ネットワーク機器にも補完入力はありますが、コマンドが全て入力されていることは必須ではありません

  ! Cisco IOS-XE
  
  #show version
  Load for five secs: 3%/0%; one minute: 3%; five minutes: 3%
  (中略)
  
  #show ve
  Load for five secs: 3%/0%; one minute: 3%; five minutes:
  (中略、エラーにならない)
  
  #show v
  % Ambiguous command:  "show v"
  #
  ("show v" 以後に続くコマンドはversion 以外にもあるためエラーとなる)
  

  • オペレーションには便利ですが、しかしながら手順書では必ずしも省略すべきではない場合もあります
    • そのコマンドを実行することが珍しいものである場合、未来にコマンドで検索され、手順書が再利用されることを想定して省略せず書くべきです。

  手順の正しさ

  • 確認は複数方法で
    • ここでいう"確認" は手順を実行する前/後の状態確認を刺します
    • ある一つの状態を確認するために、複数の手段を用いて確認すると効果的です。
      • ping 疎通は異なる複数の送信元から
      • ARPテーブルとarping
      • などなど。社内の例だといくらでも思いつくんですが一般的な例が出てきませんでした
  • 検証で確かめる
    • 初めて実施する作業は、多くの場合検証して効果と安全性を確かめてから本番に実施することと思います。
      • 検証した結果は、統一的に管理されているべきであり、検証に続く全ての作業においてもいつでもこの検証結果を参照できる状態にされているべきです。

  そうは言っても

  • 細かいことをざっくばらんに書き連ねましたが、全員がこの内容を理解し、
    常に遵守しようとしたら運用はまったく回りません。
  • 従って、正論は正論として、実情との棲み分けを考えないといけません。

  ---

  • 自動化から逃げない
    • まずは人間がいちいち作業を行っている状態から抜け出したい。自動化の大切さは今更自分が言う必要は無いでしょう
  • 手順書から逃げない
    • レビューでクソ細かいことを言われるとしても、手順書をちゃんと書くことから逃げてはいけない
    • レビュアーは作業者の心理的安全性を考慮しなければならない
      • レビュアーは、適切な指摘を、理由を添えて謙虚に行うべきです。
  • 手順書は再利用する
    • 前にやった手順は容赦なく再利用しましょう。ただし、以下に留意する必要があります
      • 再利用することの妥当性
      • 再利用した/している事実の明記
      • 再利用できる部分・できない部分の明確な区別
  • フォーマット化する
    • どの作業でも共通になっている事項は、もちろんフォーマットを用意して手順書作成の手間を減らすべきです。
      • 事前事後確認、管理資料の参照、遵守事項など
  • やはり図表を用いる
    • 何十行の文章よりも、一枚の図の方が構成を理解しやすいです。
    • この記事もそう。図を用意したかったですが、時間的都合でできなかった。こういう手順書の書き方をしているといつか事故ります

  まとめ

  • いかがでしたか？
    この記事では手順の書き方について最近思っていることをまとめたつもりですが、
    殴り書きの感もあるので適宜見直して修正していきたいと思っています。

  • 人が書く手順書のgit 管理って効果的なのか誰か教えて欲しいです

    • 手順書のテンプレートならまだしも、手順書自体はバージョン管理する効果がなさそうと思っているものの確かめてられていません