メイラボ開発者ブログ

株式会社メイラボのエンジニアブログ

プログラマー初心者が手順書作成で重要と思ったこと

f:id:a_kojimanu:20190509211605j:plainプログラマーなのに手順書作成を頼まれた!

「手順書作成なんて初めてだからどうしよう!」

「構成はどう書こう?」

「どのくらい書けばいいの?」

「自分が書いた内容は間違いないか?」

「自分にはまだ早いのでは?」

などと思った人に少しでも参考になればと思い今回の記事を書くことにしました。

このような思いに悩んでいる人へ、僕がこれは重要だろうと思ったことを伝えます。 その前に今回の記事を書こうと思った経緯について触れます。

きっかけとしては、システム移行手順書を書くことになったのが始まりです。 システム移行については、社外のお客さんも関係してくる作業なので、綿密に内容を考える必要がありました。 その為チームの人と相談しつつ、今回書く内容を考えながら手順書作成を進めましたので、少しでも参考になればと思います。

本記事の伝えたいこと

  • 目的を考える
  • 構成を考える
  • 方法の決め方を考える

上記のことが重要と考えていますので、それぞれ説明します。

目的を考える

まず自分が書こうとしている手順書はなぜ書く必要があるのかを考えます。 誰に対して、何のために、読んだ人にどうなって欲しいのか。

例:新人社員用にシステム開発の為に必要な環境構築手順書を作成することになった。

  1. 誰に対して:新人社員
  2. 何のために:システム開発の為に必要な環境構築出来るように
  3. どうなって欲しいか:手順書を理解して説明出来るように

あくまで例なので参考程度に見て欲しいですが、「誰に対して」、「何のために」は必要です。 そうでなければ、書く内容に不足や余分が発生してしまいます。

構成を考える

構成を考えます。どの項目にどういう内容をどういう目的で書くのか。 目的を考えることは構成を考える上でも重要です。

例:新人社員用にシステム開発の為に必要な環境構築手順書を作成することになった。

  1. 前提
    • 内容:作業者がどういう状況であるのか
    • 目的:前提に書いてある人向けの手順であるということを伝えるため
  2. 全体スケジュール
    • 内容:環境作成の全体的なスケジュール
    • 目的:スケジュール、所要時間を伝えるため
  3. 作業者
    • 内容:作業者
    • 目的:手順書を読んで作業する人を伝えるため
  4. 事前準備
    • 内容:何が必要になるのか
    • 目的:事前の準備が必要かどうか、何が必要なのかを伝えるため
  5. 注意事項
    • 内容:作業をする上で注意しなければならないこと
    • 目的:これだけは必ず守って欲しいということを伝えるため
  6. 手順
    • 内容:環境構築手順
    • 目的:実際に作業して構築出来るように理解してもらうため

上記の例で言えば、前提と事前準備については目的を決めないと同じ内容を書いてしまう場合があります。 読みづらく、まとめにくくなってしまうため注意しましょう。

方法を考える

自分が必要と考えた手順に対して、解決するための方法を探す作業があります。 探し方はネットや本、人に聞くなど様々です。探すのは当然です。 重要なのは下記です。 - 方法を1つ見つけて終わりにしない - 他に方法が無いか探してみる - 他に方法があればどれがベストな方法であるか考える - 方法を見つけたらその方法を自分で試してみる - ベストな方法が決まったらなぜそれを選んだか理由を言えるようにする

どうしても1つの方法しか見つからない、考えられないとなった時は、そうなった経緯を説明出来るようにしましょう。 人に聞くとなった時に、理由を言えないとアドバイスが無駄になったり、自分の知りたかったことが知れないという状況になる可能性があります。

まとめ

初めて、慣れてない人が理想的な手順書を作成することは難しいです。 出来ないことは出来ないと噛み締めて、じゃあなぜ自分はこう書いたのかを説明出来るように考えて作ることも重要です。 「ネットにこう載っていたので」というのは、レビューをしてくれる人、手順書を読む人、自分にとってもメリットが少ないです。自分の意見・考えを取り入れて作成することを意識しましょう。