背景
新卒1年目のエンジニアです。
エンジニアの中で時折、「コード読めばわかるよ！」「公式ドキュメント読めばわかるよ！」というやり取りがあります。
言われた時に実際に対象のドキュメント、コードに目は通したけど、問題が改善されないことがありました。
また、自分もこの発言を使っているように思い、その際に課題解決に強くつながった感覚がないです。
確かにドキュメントにはレビューの問題解決に関わる情報は書かれています。
しかし、「ドキュメント読めばわかる」は、度々お目にかかるフレーズではあるが果たして良い解決策とは言えないと考えています。
対象読者
- レビュワーとの技術的理解度にギャップがある場合は、新人エンジニア
- 会社のドメイン知識に乏しい、新規ジョイン者
- 新しい分野を勉強している方
執筆の動機
「ドキュメントを読めばわかる」は、自分も同期に使ってしまったことがあります。あまりいい解決策でないと思いつつなぜ使ってしまうのか、どうしたらいいのか、思考を整理したかったです。
その背景に沿って、新人の立場ながら、「ドキュメントを読めばわかる」を深掘りしました。
また自分を含め多くの人は、分かるようになると分からない人の気持ちがわからなくなってしまいガチだと思っています。
なので、わかる側/わからない側、どちらが悪いという類の問題ではなく仕組みと意識の設定で解決できると思って記事を書きました。
目的
「ドキュメントを読めばわかる」を言われる側、言う側に分けて原因と対策を書きやり取りの参考になればと思います。
また、メンター/メンティーとしてのやり取りの参考になればと思います。
言われる側： なぜドキュメント読んでもわからないのか？
前提コードを正しく作ろうという熱量と、ドキュメントに目を通す素直さを持っていても問題解決につながらないことがあります。
なぜでしょうか？
原因：背景と目的を理解していない
体感ですが多くの場合、そのコードが書かれている背景と目的がわかっていないと、ドキュメントを読んでも必要な情報を抽出できないです。
なぜ？の深掘りを、背景・目的の観点で行うと、明確なアクションを起こせました。
システム要件定義でも解決策だけではなく、背景・目的から定義するということから考えることで理解できました。
こちらの記事が大変参考になりました。
「背景と目的を理解していない」は、「全体像が理解できていない」とも言い換えられます。
全体像を理解していないで改修すると、仮に課題解決できたとしてもレビューを盲信する結果に陥ります。
対策：全体像を理解する
いい物を作るためには、全体を知ることが大事です。逆に言えば、部分だけをみている（今回で言えば単体のレビュー・要件だけ）をみていると、ミスコミュニケーションが起こります。
引き合いとして、円柱の認識があります。円柱をAさんは側面から見ているので四角に見えるし、Bさんは真上から見ているので円に見えます。
両者が言っていることは正しく、部分で語ることによる不足を表現するいい例だと思っています。
『エンジニアリング組織論への招待 ~不確実性に向き合う思考と組織のリファクタリング 』 1章を参考に作成
アクション： ドキュメントだけで全てを理解しようとしないで相談時間を抑える
先輩の時間を取らせるのが申し訳ないと思うかもしれませんが、時間をおさえて理解しましょう。ドキュメントを読むだけで全てを理解しようとしていることが、良い解決策ではないと思いました。
ただし時間をもらう限り最大限情報を引き出せるように、相談の準備するように工夫しました。
相談する際のチェックポイントは下記のように設けています。
ポイント1 仮説はあるか
自分なりの意見を持ち、オープンクエスチョンは使わないようにしましょう。
良くない相談： 「このドキュメントのどこを読めばいいのでしょうか」
良い相談： 「このドキュメントの〇〇が対象箇所だと思いました。それで読んだ結果、△行目までしか理解できませんでした。それ以降の解説をお願いしたいです。」
ポイント2 思考を形にできているか
わからないことが多くても、最低でも思考の流れのメモを持参したほうがいいと思いました。思考の流れの中で、ここはOK、ここは惜しい、と言われたほうが意見を擦り合わせやすいなと。
良くない相談： 「わからないところがわからないです。。」
良くない相談： 「問題をA,Bに分解したのですが、A,Bの分解で合っているかがわからないです。。」
言う側： なぜドキュメントを読んで、と伝えてしまうのか？
同期にドキュメントを読んだら分かると言ってしまったケースを題材に深掘りをしてみます。
df.assign(
new_score_rank = lambda df: df.apply(lambda row: attach_score_rank(row['new_score']) , axis=1)
)
pythonに慣れていない同期から、上記コードがわからないという質問をもらいました。
その際のやり取りです。
自分 「このコードのどこがわからない？」
同期 「lambda, applyのところが良くわからなかった」
自分 「pandasのapplyの公式ドキュメントやlambdaについて調べた？」
同期 「webの記事は調べたけど、使いどころが良くわからなかった」
自分 「pandasのapplyの公式ドキュメントに使い方載ってるから見たほうがいいよ！それでわからなかったらもう一回聞いて！」
....
同期 「やっぱわからなかった！」
自分 「じゃあ一緒にみよう！」
その後、ペアプロ的にやり取りをして問題を解消しました。
なぜ「ドキュメントを読んで」、と伝えたのでしょうか？
原因： 課題解決にドキュメントを読むことが必要だから
確かにドキュメントを読むことが課題解決につながるのは事実です。そしてその手順のみを伝えてしまいました。
しかし、ドキュメント読むことは必要条件だが十分条件ではない です。
対策&アクション: 一緒にドキュメントを読む
読んだ上でもわからないことがある、という前提があるのでもう一回聞きに来て！と言ってはいますが、
- ドキュメントで読んでほしい箇所と内容が擦り合っていない
- applyのユースケースを見ることでなぜ解決になるかわからない
ので同期一人で解決には至りませんでした。
一緒に読むことを前提にして、少なくともドキュメントのどこを読んで何を知ればいいかまでは、一緒に見ることが大事だと思いました。
学び
下記２つの前提を置くことが大事だと思いました
- ドキュメントなりコードは課題解決のために書かれてはいない
- 完璧なドキュメントは存在しない
1の前提は、ドキュメントを渡しっぱなしになることを防げます。
2の前提は、「これさえ読めば誰でもわかる」という過信を防げます。
その上でわからない側では、ドキュメントだけで全てを理解しようとしないで相談時間を抑える が良い解決策だと思いました。
ドキュメント見てわからない箇所と質問事項があるので、相談時間もらってもいいですか？
その上でわかる側では、 ドキュメント読むことは必要条件だが十分条件ではない を前提とした一緒にドキュメントを見るが良いと思いました。
このドキュメントに必要な情報が載っているので、一緒に読みながら修正しましょう
「ドキュメントから読み取って欲しい」対象が相手とすり合っているか、相手が疑問に思っている箇所を受信できているかを確かめながらドキュメントを読むのが解決策になるのだと思いました。
こちらの記事が大変参考になりました。
まとめ
「ドキュメントを読めばわかる」は、自分も同期に使ってしまったことがあります。そして、今後も使う場面はあると思います。
しかし、上記の前提や対策を踏まえたコミュニケーションを取れば、より良いエンジニア活動ができると思いました。
また適切な前提を持つことが一層大事だと思いました。
共有ドキュメントは「共通理解」ではない
『ユーザーストーリーマッピング』 0章より抜粋
今回の記事を書くにあたって、コミュニケーションを意識することで解消される問題があると実感しました。
強く優しいエンジニアになれるように日々精進していきます。