仕事をしててドキュメントの書き方を整理してみたいなと思った。
そこでこれを書くといいのではとか、これを気を付けるべきだなと思った
ポイントを書いてみる。
内容はこれをやったら一流になれるとかではないので
タイトルはいろいろ考えて、控えめなニュアンスを含めたらこうなってしまった。
ドキュメントは最初からしっかり書いておくと
上司からの突然の質問に答えやすかったり、
進捗会議で答えやすかったり、
後輩に仕事を分けるとか引継ぎが楽になるなど
非常にメリットがいっぱいだ。
だからしっかり書いた方がいいと思う。
だけどいつもいつもうまく書けてなくて困ることが多いんだけどね。
なにを書くか？
ざっとあげたところドキュメントに書く内容は
下記かなーと思っている。
- 経緯
- 概要
- タスク調査
- スケジュール
- 修正概要
- デプロイ方法
- 実行・反映
- 実行ログ
- 変更後の経過
一つ一つ説明してみよう。
経緯
最初からこれはかなり大事だと思っている。
「この作業案件はそもそもなんでやらないといけないんだ？」
とか、作業の始まりでも途中でも「そもそも」がたびたび思い起こされることがある。
そして、後輩から聞かれて答えられないとか。。。
また自分の作業を振り返った時や
同じような作業をする時に、ドキュメントを探して
「あれ？あの時なんでこれやることになったんだっけ？」となることが
よくあったので、作業をやる経緯を簡単に書いておくと
未来の自分にメリットがある。
概要
作業の概要を簡単に書く。2，3行で。
その時に、ざっくりとどんな作業をしてさらにどんな効果・メリットがあるのか
期待しているのかを書いておくと、知らない人にドキュメントを読ませるときに
わかりやすくなる。
この概要は経緯とあわせてもいい。
どうしてどうやってこの作業をやるのかを
ざっと書いておくと目標がはっきりしてくる。
タスク調査
ざっくりやることが決まったら、細かいタスクとして何をやらなければいけないかを調査してリストアップする。
よくやりがちなんだけど、すぐにプログラミングの修正すればいいやと思って
やり始めたら、別の要件があってそれが別部署と交渉が必要だったりして
せっかくやり始めた修正が無駄になったってことはよくありました。
「お前その分の時間返せよ！」と怒られたこともあります。。。
いきなり手を付ける前に、細かい部分の作業の全体感をとらえるのはとても大事。
そのために何をしなければならないかの見積もりをする。
それをリストアップする。
これがかなり大事。
ここで、自分がまだぺーぺーなのでそういう立場にないという人は
周りや上長のやってることから推測して勝手に全体感を予測してみましょう。
そのうえで自分のやってることを見返すと自分の作業の意味がまた深まります。
またこのリストアップ作業を仕事じゃなくても、飲み会でもなんでもやる癖をつけておくと
今後自分がリーダーになった時に周りや部下に仕事をふることができるようになります。
なのでかなり大事。
修正概要
どうやって修正するかです。
ソースコードであればプルリクのリンクを載せておくでもいいし
サーバー構成変更であれば、設計図を書くなりしましょう。
いきなり修正しないことです。
細かい部分で関係者に修正内容の合意を取る、検討してもらうことが目的です。
デプロイ方法
修正概要とほぼ似てます。
修正の本番反映はかなりデリケートにやらないと障害が起きるので
ローリングアップデートするのか、時間帯はいつにするのか
などを書いておきましょう。
実行・反映
修正概要、デプロイ方法で関係者に合意をとったら
反映方法手順書を作りましょう。
これはもう、書いた内容をコピペしたら実行できるというレベルでやります。
テスト環境などを使って作りましょう。
実行ログ
本番反映をしたら、やっぱりテスト環境とは違うので
想定外の現象が起きるかもしれません。
また実行時間がかかるかもしれません。
やったことのログや時刻を逐次書いていきましょう。
変更後の経過
これが忘れがち。
あーやっと本番反映したーと思ったら、確認してなくて
実は本番に反映されてなかったなんてこともあります。
何をしたらちゃんと反映されているかをきちんと確認しておきましょう。
ここまでざっくり書きましたが
毎回細かく書くこともないかもしれないし、どこかをはしょるかもしれません。
別の人に聞いたらぜんぜん違うこと言うかもしれません。
ですが、作業の全体感を把握して説明ができることをかなり大事に心がけた方がいいと思います。
お客さんや上長はその作業をやる必要があると思ってるけどリソースが足らない。
だからこそお前にやらせてるのだ。
だからこそ作業の透明性や説明責任が必要になるのだ。
この辺のことができるとプログラミングが少々秀でてなくても
なんとか現場でやれるはずだと思ってます。
IT業界に3か月で転職したくない人はクリックしないでください
書くスキルUP すぐできる! 伝わる文章の書き方 確実に文章力がつく! 7つのステップ
- 作者: 赤羽博之
- 出版社/メーカー: 日本能率協会マネジメントセンター
- 発売日: 2013/03/20
- メディア: 単行本
- この商品を含むブログを見る
伝わる! 文章力が身につく本 (基礎からわかる“伝わる!"シリーズ)
- 作者: 小笠原信之
- 出版社/メーカー: 高橋書店
- 発売日: 2011/01/29
- メディア: 単行本（ソフトカバー）
- 購入: 4人 クリック: 55回
- この商品を含むブログ (7件) を見る
