継続は力なり―大器晩成エンジニアを目指して

第9回ログのすすめ

今回のテーマはログである。ログと言ってもサーバやアプリケーションのログのことではない。今回取り上げるのは作業ログである。作業ログと言えば、古くはChangeLogメモhowm最近ではEvernoteやMarkdown形式でのメモなど、いくつかの流派が存在する。

作業ログを取る目的はさまざまだ。ライフログ、つまり自分の人生のログを取る目的のものもあれば、未来の自分が検索することを見越して書くものもある。今回取り上げるのは、物事を前に進めるための作業ログである。筆者は記憶力が悪い。暗記モノが昔から苦手だ。また、気が散りやすく数分前に何をやっていたかさえ思い出せないこともある。そんな限られた能力で、難しいタスクをこなすためには工夫が必要である。そのための工夫の一つがログを取ることだった。今回はその作業ログについて、できるだけ実例に近いものを取り上げながら説明したい。

難しいタスク

仕事で、あるタスクを任されたとしよう。タスク管理システムのチケット上で見るとそのタスクはシンプルだ。⁠システムAで使われている、便利なフレームワークBをシステムCでも使えるようにする⁠⁠。さっそく仕事にとりかかる。しばらくあれこれ試行錯誤してから気付く。この仕事は思ったよりも手強いぞ。まず20~30ページほどのドキュメントを読んで、既存のシステムを理解しないといけない。各ドキュメントページにはたくさんのリンクがある。すべて読む必要があるのだろうか。一部のドキュメントはしばらく更新されていないように見える。内容が古い可能性もある。フレームワークBは設計思想が今まで触ったものと違うので戸惑う。システムAを担当していたエンジニアに言わせれば「まあたぶん動くんじゃない」とのことだが、怪しい。フレームワークBとシステムAの両方に精通した人は誰もいなそうだ。とりあえず動くプロトタイプを作ろうと手もとでコードを書き始めるが、大量のエラーが出て動かない。動くようにするだけでも、少なく見積もっても数日以上はかかるだろう。

状況の難しさをまとめてみよう。

  • 大量のドキュメント
  • 動くコードがないので試行錯誤が必要
  • 作業が数日以上にまたがりそう
  • 質問や相談できる人があまりいない

このようなタスクには作業ログがぴったりでお勧めである。以下、それぞれの項目についてログの活用を説明していく。

大量のドキュメントとログ

よくあるドキュメントのパターンは、Getting Startedページにイントロダクションがある。そのあとはチュートリアルで、次へ次へとリンクが進んでいく。ある程度進むと「Advancedな内容はこちら」で終わる。各ページでは「次のページ」リンク以外にもAPIドキュメントやその他(コーディング規約、インストール方法)など複数のページにリンクがある。

筆者の失敗パターンは、最初から「ふーん」と流し読みしていく。適当にリンクをクリックして読み進める。どうやら最後まで到達するが、いまいち頭に残っていない。いろいろなリンクを見逃している気がする。ドキュメントを読んだとも読んでないとも言えない、何やらもやもやした状態になってしまう。

大量のドキュメントの問題点は、

  • [a]読み逃しへの不安
  • [b]あとで必要なものを見つけられない不安

の2つである。[a]については読んだドキュメントのすべてのリンクをログに残していけばよい。可能であれば各リンクについて再読の必要性や、1行まとめを追加しておこう。ドキュメント本文は必ずしも全文読む必要はない。その時点でわかる範囲での重要度に応じて時間をかければよい。[a]もログに短いメモを残しておけばよいだけである。

こういう状況では、リスト1のようにネストした箇条書き構造で作業ログを取るとよい。上から下に読んだドキュメントを列挙していく。筆者は先述のMarkdown形式で書いている。そしてリスト1 のように、終わったところはdone、今読んでいるところはhere とマークしている。1つのドキュメントから別のドキュメントにリンクがある場合は、リスト構造をネストして表現している。このようにログを取ることで、大量のドキュメントを読むときの心配やストレスが軽減される。

リスト1 ドキュメントの作業ログ
- __done__ [API document](...)を読んで1行にまとめる
    - __done__ [BについてのDesign document](...) 再読必要なし
        - __important__ [configの方法](...) あとでここのセキュリティ項目を見る
- [deploy document](...)
    - __here__ [OAuthについて](...)
    - [DIについて](...)

なお、筆者はこの作業を効率化するためにMarkdown形式のリンクを生成するブックマークレットを使っている。Webで検索すればすぐに見つかると思うのでお勧めである。

試行錯誤とログ

動いているコードがないので、それを動くようにするのに試行錯誤が必要である。たくさんの試行錯誤をしているときに困るのは、⁠自分がどこで何をしているのか」がわからなくなることだ。時間の節約のために2つのことを同時に試してみる。作業中にチャットで話しかけられる。作業が日をまたぐ。あっという間にどこで何をしているのかがわからなくなる。

試行錯誤はツリー構造であることが多い。複数の枝X、枝Y、枝Zと順々に試していく。場合によってはX1、X2など枝Xの中に降りていってさらに試行錯誤をする場合もあるだろう。これらをツリーとして描くと、自分がどこにいるのか、どこに戻るべきかが明白だ。

ツリーを絵として描くのは面倒なので、その代わりにリスト2のようなログを利用する。先ほどと同様にネストしたリスト形式だ。このようにリスト構造でツリー構造を再現すれば、⁠自分がどこで何をしているのか」が一目瞭然である。

リスト2 試行錯誤の作業ログ
- システムAをローカルで動かしてみる
    - __done__ ライブラリDが必要らしい
        - __done__ dependencyに追加した
    - __here__ スタックトレースを見るとDIで失敗している
        - そもそもそのdependencyは必要なのか
    - 本番サーバのconfigを見てみる
- システムAをデバッガで動かしてみて処理を追う

復帰ポイントとログ

タスクが1日で終わらない場合、前日の作業から復帰しなければいけない。ドキュメントを読んでいたかもしれない。複雑な試行錯誤の途中だったかもしれない。ログを残していれば、先述のhereとマークを付けたところを検索して前後のログを読む。そうすれば簡単に作業を再開できるだろう。

相談相手としてのログ

ここまでは主に記録としてのログを取り上げてきた。だが筆者はログの一番大事な部分は「対話」だと考える。相談相手がいない状況を、ログを記録することを通して自分自身と相談しながら進んでいるのだ。自分にとってログをわかりやすく書こうと思う。自然とその事柄についてより深い理解が必要であることがわかる。自分が何をしようしているのか、どのような状態なのかを把握することになる。このように擬似的な客観性を持ちつつ自分自身と対話する。そのことが「作業を進める」助けになるのだ。

筆者はわからないことを、リストとしてログにまとめている。それぞれの質問の答えに近付くにはどうすればよいか。リストに書き足していくと前に進める。わからない状態のまま進む場合もある。答えがわかった時点で疑問点に立ち戻ればよいのだ。やってはいけないのは、誰にも相談できず、頭の中でぐるぐると堂々巡りになることだ。ログと相談しよう。

まとめ

複雑な作業をしているときは、自分がだめなループに入っていたり、パニックになっていたりすることに気付きにくい。筆者はそのような状況に陥ったことが何度もある(あとから気付いた⁠⁠。作業ログを書くことでより客観的な目線を手にできる。みなさんの作業効率が少しでも上がれば幸いである。

WEB+DB PRESS

本誌最新号をチェック!
WEB+DB PRESS Vol.130

2022年8月24日発売
B5判/168ページ
定価1,628円
(本体1,480円+税10%)
ISBN978-4-297-13000-8

  • 特集1
    イミュータブルデータモデルで始める
    実践データモデリング

    業務の複雑さをシンプルに表現!
  • 特集2
    いまはじめるFlutter
    iOS/Android両対応アプリを開発してみよう
  • 特集3
    作って学ぶWeb3
    ブロックチェーン、スマートコントラクト、NFT

おすすめ記事

記事・ニュース一覧