【エンジニア必須】何でも文書化のススメ
人はみな平等に忘れる
皆さんはお仕事やプライベートなどで起きた出来事を文書にきちんと残していますか。
今はその事象に対して「ものすごく知っている状態 (100%)」だとすると、明日には70%くらいまで落ちてるかもしれません。
1ヶ月後、3ヶ月後、6ヶ月後はどうでしょうか。その時にも事の詳細を明確に覚えている人はどれくらいいるのでしょうか。どんなに記憶の天才でも、全ての事象を事細かく覚えている人なんて居ません。(サバン症候群などの例外は除きます)
人は忘れると言うことを前提に毎日の生活にひと工夫加えるだけで、周りと大きく差をつけることができます。
それが「何でも文書化のススメ」です。
文書化する上で必要な要素
何かを書く、と言っても単なる一言、二言だけでは足りません。物事を伝える時には「いつ、どこで、誰が、何を、どのように」などの説明要素が必要です。
例えば「ご飯を食べた」だと、その当事者はいつ、誰とどこで、食べたのかが分かりますが、第三者には意味不明です。
そしてあなたは半年後に、その言葉を目にしても「何じゃこれ」と言うことでしょう。つまり時間が経てば、その事象に対してあなたも第三者になるのです。
その一文に以下のように書き加えてみます。
「昨日、渋谷の吉野家で友人とご飯を食べた」
この一文を第三者が見た時に、最低限の理解が出来るようになります。お店の中での状況、会話などは分かりませんが、少なくとも何が起きたのかは分かります。
そして人に伝わる最強の文章構文は、実は昔話の「桃太郎」を真似すると良いのです。
桃太郎の始まり
「昔々、あるところに、おじいさんとおばあさんが住んでいました。おじいさんは山へ芝刈りに…」
これを分解すると、
昔々(いつ)、あるところに(どこで)、おじいさんとおばあさんが(誰が)...山へ芝刈りに(何を)
上記のようにはっきりと誰が何をしているのかが伝わってきます。昔話「桃太郎」はあまりにも有名すぎていちいち本を読みながら思い返す人は少ないでしょう。
人に伝わる文章は、このように伝わる要素があるからこそ伝わるのです。
何でも文書化とは？
多くのエンジニアは、自分の好きな領域以外で仕事をするのを嫌う傾向があります(ボク調べ)
その嫌いな作業の中に「起きた出来事の文書化」が含まれます。
コードを書く人であれば「何でこのコードをこのように変更したか、コードを見れば明らかでしょ」と言うかもしれません。ただ、それを毎回第三者に説明して回る必要があるとすれば、どうしますか。
口頭で何度も同じ説明をするのでしょうか。そんなことをやっていたら1日が説明だけで終わってしまいます。
そうならないためにも「昔話桃太郎」を思い返して最低限の要素を取り込みましょう。
バグ修正の説明例
- いつ: 2020-11-06 08:00 (UTC+9)
- どこで: 開発環境
- 誰が: 直前のコミットされたコード
- 何を: 特定のAPIでエラーを返す
- なぜ: エラーが発生したから
いかがでしょう。こうやって説明をすると何でその行動をするに至ったのかをきちんと理由つけすることができます。
このレベルの説明ですら省略するエンジニアが多い環境の場合、逆にあなたがこれらをまとめ上げることが出来ればそれが1つの仕事、スキルになります。
文書化する、はあなたの武器になる
多くのスタートアップで起きる問題の1つに「ドキュメントが全然そろってない」があります。
これは先に説明した「昔話桃太郎」の必要最低限の説明要素を残さずにサービス開発を進めた結果とも言えます。エンジニア以外でも、この文書化すること、は非常に大切で、これが出来る・出来ないだと「周りの人達によるあなたの評価」が大きく異なります。
「あの人、仕事はめちゃくちゃ早いけど、ドキュメント残さないし、あの人しか仕事できない状況になってるよね…」
とか言われてるかもしれません。
ではなく、文書化をきちんと行うことで「あの人、仕事もできてきちんと情報整理することができる」と言う評価の方が良くないですか。
わかったわかった、けどどうやって文書化すればいいねん
文書に残す大切さは理解したけど、どうやって記録に残せば良いかが分からない人は「Notion」を使ってみましょう。最初は自分に向けてメモを書き、外部・内部公開してみよう、と言う気持ちが湧いてきたら公開するのが良いです。
具体的なやり方は下記が非常に参考になります。
新しい技術を学習しながらNotionでメモをとり、Zennで効率よく記事化するフロー
まとめ
- 文書化する時のコツは桃太郎を思い出す
昔々(いつ)、あるところに(どこで)、おじいさんとおばあさんが(誰が)...山へ芝刈りに(何を)
- Notion + Zenn を使って記事を管理すると非常にはかどる 😄
Discussion