くらしのマーケット開発ブログ

「くらしのマーケット」を運営する、みんなのマーケット株式会社のテックブログです

エンジニアの「ドキュメントよりコード書きたい」を本気で解決してみた!

f:id:curama-tech:20200710184201p:plain

こんにちは、みんなのマーケットでCTOをしている戸澤です。

今回は、長年に渡って整備できなかった開発ドキュメントを、全員で整備する取り組みをはじめた、という内容です。

本記事は、6/10に開催した「失敗に学べ!くらしのマーケットの開発「失敗」LT会 vol.1」でのLT内容を再構成したものです。

課題

テクノロジー本部の長年の課題の1つに、「ドキュメントがない」 というものがあります。 ドキュメントがないと、

f:id:curama-tech:20200710184255p:plain

開発や環境構築などのわからないことは、Slackや口頭で聞く必要があります。 この状況では、教える側がその対応に都度時間を使う必要があり、また、内容も記憶頼りになり正確かどうか保障ができません。 特に教える側は往々にして忙しいことが多く、聞く側からすると、聞きづらい雰囲気の場合があり、ゆえに、聞く側が自己解決を試み時間がかかったり、聞かずに放置されてしまうということが起こります。

反対に、ドキュメントがあると、

f:id:curama-tech:20200710184306p:plain

聞く側が自主的に探せるようになり、また、探せなかったとしても、教える側が「xxxで検索してみて」と、キーワードを伝えることで解決できます。 それにより、教える側が都度対応していた時間を減らすこと、聞く側の聞きづらさの解消ができます。 また、内容が記憶頼りではなくなり、内容の間違いや忘れを防止できます。 さらには、教える側の使える時間が増えるため、ペアプロなどより価値の高い時間の使い方ができるようになります。

このようなメリットがあるとわかっていても整備が進まないのが、ドキュメントです。

どうすれば、ドキュメントを充実させていくことができるのでしょうか。

そんな中、ある方から次のようなアドバイスをもらいました。

転機

f:id:curama-tech:20200710184317p:plain

f:id:curama-tech:20200710184329p:plain

たしかに、コードとドキュメントどっちに時間を使うべきか迷ったり、一人で書こうとして整備が進まなかったドキュメントですが、みんなで同時に書くのであれば、時間の設定や全員の責任として、書くことができるはずです。

これは良いのではないか、ということで実施してみました。

やってみた

実施にあたって、次の3つのポイントを決めました。

  1. ドキュメントのフォーマット
  2. ドキュメントの項目
  3. イベント化する

順番に、 f:id:curama-tech:20200710184343p:plain

まずはゴールを決め、そこに求められるドキュメントのフォーマットを決めます。 今回達成されるべきゴールは、そのドキュメントを他の開発チームが読んで理解できることです。 現在の状態では、フォーマットを詳細に決めてもそれを全て守ることに頭を使ってしまうので、ゴールが達成に必要な必要最低限のものだけにします。

記事は、機能単位の粒度で1つの記事にまとめます。 記事が長くなる可能性がありますが、それよりも記事が分散し探す手間が増えたり、更新漏れの発生を防ぐためにまとめます。 今後、記事が長くなってから分割することを考えればよく、まずは記事を書くことに集中します。 その他、事実と感想を分けることや、図や表を使ってわかりやすくすることなど、基本的なことだけ決めます。

f:id:curama-tech:20200710184357p:plain

次に、ドキュメントの項目出しをします。 チーム毎にこれまで扱った開発内容のドキュメントを書いていくため、まず項目の抜け漏れがないか確認をするため、同じ項目を複数名で同時に作成してしまうことを防ぐために行います。 どの項目から作成に着手するかはチームで判断して大丈夫です。 ただし、2,3回...と継続して取り組んでいき、どの項目もいずれ書くことになるので、優先度は決めなくても問題ないと思います。

f:id:curama-tech:20200710184406p:plain

最後に、ドキュメントを書くことをポジティブに認識していけるように、この取り組みをイベント化していきます。 また、ゴールが達成されているかの確認と、成果を出すことに意識を向けるために、ほかの開発チームからレビューをもらうようにします。 ドキュメントは全員で作成、更新していくものであり、全員が参加すること、という意識付けでもあります。

レビューが終わったら、全員で簡単にドキュメントの概要を発表しあいます。

結果

「xxxで検索してみて」と言えるタイミングが増えました。 結果として、教える側が都度付きっきりで教えていた時間を、他のことに使えています。 また、ドキュメントのレビュー時に、レビュワーが初めて知る内容もあり、そのタイミングからすでに理解が深まっていく様子でした。

今年4月に1回目を開催し、毎月1回開催し、6月までに計3回開催しました。

ドキュメントは増えてきましたが、カバレッジをもっと上げるために今後も月1回で継続開催し、カバレッジが高まってきたら数ヶ月に1回の開催のように、頻度を落としてもいいと思います。

おわりに

そもそもドキュメントがないとドキュメントの有用性を理解できなく、ドキュメントが書かれないという悪循環に陥ると思いますが、ドキュメントのカバレッジが上がり、日常的に使うようになってくると、逆にドキュメントがないことが目立つようになってくると思います。 そうなると、このような取り組みをしなくても、その気持ち悪さから自然とドキュメントを作成し、そこを補完しようとする気持ちに私はなると考え、今後はカバレッジが上がるにつれて、ドキュメントを書くカルチャーも根付いてくるのではないかと思いました。