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

第9回 ログのすすめ

この記事を読むのに必要な時間:およそ 2 分

今回のテーマはログである。ログと言ってもサーバやアプリケーションのログのことではない。今回取り上げるのは作業ログである。作業ログと言えば,古くは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で検索すればすぐに見つかると思うのでお勧めである。

ログは公開すべきか

機密情報が含まれないのであれば,ログを公開することをお勧めする。実際に誰かが見ているとは限らないが,他人の目にさらされると思うだけでログのクオリティが上がる。作業効率も良くなると実感している。GitHubのWikiが手軽でお勧めである。

著者プロフィール

ひげぽん(Taro Minowa)

Software Engineer.

Mona OS/Mosh Scheme

URL:http://www.monaos.org/
技術ネタ:http://d.hatena.ne.jp/higepon