Chapter 18無料公開

┣ 作りながらレポートを書いて、資産にする

Yoshio Kakehashi
Yoshio Kakehashi
2021.12.10に更新

作り方を忘れる前に残す

我々の担当するプロジェクトは2-3ヶ月周期と短い。次に担当する3ヶ月後のプロジェクトでは、まったく違う技術を使っていることだろう。当然、過去に作ったものや、問題解決の方法は忘れていく。

問題解決に費やした自分のリソースを、目に見える資産にすべく、メモやログ、レポートを残しておこう。

俺はInkdropやNotionに残している。

レポートを書くことで得られるメリット

  1. 自分の作り方を残す
  2. 問題にぶつかり、レポートを書いているうちに、解決することもある
  3. 自分用のレポートを手直しするだけで、すぐに報告したりブログで公開できる

1. 自分の作り方を残す

特に新しいことを試すとすぐに忘れてしまう。数カ月後、あるいは数年後に同じことを試すことも多いだろう。
コピペで瞬殺できるように残しておくべきだ。

ただし、ググればすぐコピペできるようなことはググればよい。ググってもでてこない「自分がたどり着いた作り方」を残すのだ。

2. レポートを書く間に、解決することもある

問題を言葉に変換すると、問題に対する解像度が上がっていく。熊のぬいぐるみにバグの状況を話しかけることで、頭が整理され、その場で原因がわかる。といった手法もある
ベアプログラミング(テディベア効果)

3. 自分用のレポートを手直しするだけで、すぐに報告したりブログで公開できる

問題の報告をするときに、何が問題かをいちいち調べ直すと時間がもったいない。きちんとログを取っておけばすぐに報告できる。

同様に、社内向けのブログや外部へ公開する技術ブログなどにも、転載しやすい。コピペできるデジタルデータなのだから、存分に有効活用しよう。

どのようにレポートを残すか

見返したときに記憶が蘇りやすいように、わかりやすく読みやすく記録する。

スクショや動画キャプチャなどは必須

体験ものならスマホでビデオ撮影もしておく

共有ノートアプリで残すと文章を書く訓練になる

自分の好きなノートアプリに残すのもよいが、社内の共有ノートアプリにも積極的に残すとよい。プロジェクトに関係がなかったひとにもわかるような文章を書く訓練になる。

記録の型を決めて簡潔に書く

レポートの型を作ると読みやすさもアップするだろう。

  • 課題や障害の概要
    • イージーなことまで書くと読み返すときにノイズになる。ほどほどに。
  • どの解決策を試したのか
    • どの策が役に立ち、どの策がダメだったのか
    • 対応策のパラメータも詳細に書いておくとよい
      • OS・ブラウザのバージョンなど、どの組み合わせでうまくいったのかを残すと、後々ヒントにつながることもある
  • 参考にしたリンク

原因究明フェーズでの書き方

  • 原因がわからないところを正確に書く
  • 解決策がわからなくとも現象を記録に残す。いつか解決できるときがあるかも。
  • 原因かどうかわからないが怪しいと思うところも、IDEのブックマーク機能やTODOコメントをして残しておく
    • 「なぜかこのメソッドを2回叩くとうまく動く」的な怪しい場所も、いつか潰さなくてはならないときが来る
  • 動画キャプチャも撮って、バグった状態を見返しやすくする

バグレポートの書き方も参考にするとよいだろう。型がある。

https://knowledge.sakura.ad.jp/26627/

解決したらちゃんと原因と解決策を書く癖をつける

解決したら何も書かずに次の作業にとりかかることもあるだろうが、少し立ち止まってきちんと書いたほうがいい。

どうせ忘れてしまって、次も同じ状況になる。書き残せば記憶の定着率も少しは上がる。

関連記事

正しい報告の仕方