仕様のキャッチアップ、どうしよう

はじめに

新しい会社に入社したエンジニアが必ず通るであろう道、プロダクトのキャッチアップ。
本記事では私が入社後にどのようにキャッチアップをしていったかをまとめてみました。

目次

1. 仕様のキャッチアップ
2. 背景のキャッチアップ
3. 実装方法のキャッチアップ

キャッチアップする上での材料（以下、キャッチアップ材料）

• ドキュメントツール（Notion、Cosense、esa、Confluenceなど）
• プロダクトのソースコード
• プロダクトリポジトリのPR、コミット
• Slack、Teamsなどのテキストコミュニケーションツール
• プロダクトのヘルプページ

※ 本記事では「先輩エンジニアに質問する」は最終奥義として扱うため除外します

仕様のキャッチアップ

キャッチアップ材料	相性
ドキュメントツール	△
ソースコード	◯
PR、コミット	△
テキストコミュニケーションツール	△
ヘルプページ	◎

結論、まずはヘルプページを見ましょう！！！！！！！
仕様をキャッチアップする上で参照するべきドキュメントは、以下の3点を満たすことが望ましいです

• 正しいこと
• 最新の情報であること
• 探しやすいこと

当たり前ですが、ユーザーがプロダクトについて仕様面で分からないことがあった場合、ヘルプページしか拠り所がないです。ヘルプページはユーザーにとっての公式ドキュメントなんです。
そのため、ヘルプページを見ることで基本的な仕様は全て把握できるようになっている（はずです）
エンジニアは真っ先にコードを見にいく人が多いイメージがありますが、ヘルプページの改善のためにもまずはヘルプページを確認することをオススメします！

ソースコードも仕様理解を深めるためには有効だと思います。（特に内部的な仕様などh
コードは嘘つきませんし、常に最新です。
ただ、探しやすさが入社したてのエンジニアからするとハードルがあります。（どこ読めばええんや・・・）

目的のコードを探す個人的なテクとしては

• フロントエンド側のコードの場合は、画面上のテキストなど目印になるワードでコード検索する
• バックエンド側のコードの場合は、ブラウザの開発者ツールでリクエストを確認→エンドポイントでコード検索する

最近であればAIコーディングエージェントに聞くのもありだと思います。
「**の処理を行なっているファイルを教えてください」と一発聞くだけで教えてくれます！👍

一方で、ドキュメントツール、PR、テキストコミュニケーションツールがなぜ仕様のキャッチアップに不向きかというと、これらは基本的に最新の状態に更新されないからです
つまり、最新でなければ今の仕様としては正しくもない。そして、過去現在が入り混じっているので探しにくいです。
しかし、この特性が別の観点で活きてくるので詳しくは後述！☝️

まとめ
まずはヘルプページを見よう！！

背景のキャッチアップ

キャッチアップ材料	相性
ドキュメントツール	◎
ソースコード	△
PR、コミット	◎
テキストコミュニケーションツール	◎
ヘルプページ	△

「なんでこんな仕様になってんの？」
「このコード、消したらまずいんかな？」
みたいな背景も、タスクを進めていくにつれてキャッチアップが必要になることでしょう。

しかし、最新のコードからはコメントでも書いていない限り、その歴史的背景を読み取ることは難しいと思います。
そんな時に参照するのは、ドキュメントツール、PR、テキストコミュニケーションツールです！

前述の通りこれらは基本的に最新の情報に更新されていないです。
言い方を変えれば その時々の情報をそのまま残してくれている。 ということです

つまり「歴史の本文（ポーネグリフ）」です。

しかし、これらは前述の通り過去現在のものが入り混じっており、目的のドキュメントを探しづらいです。
そんな時は下記の順序で目的のドキュメントを探すことが多いです

実装背景が知りたいコード行→コミット→PR→PRに紐づいているドキュメントorチャット

PRとドキュメントが紐づいている前提ではありますが、ドキュメントorチャットを直接探すよりこちらの方が早い場合があります。

コードからコミットを含むPRを探す場合はGitLensなどの拡張機能を使うのが良いかと思います👍

まとめるとコードを見た時に「なんでこうなっているんだろう？」と感じたら、まずはその該当コードのPRを見に行き、そのPRに紐づいているドキュメントorチャットを見る、という手順を踏んでキャッチアップしています。

まとめ
ドキュメントや過去のチャットのやりとりを探そう！
コード→PR→PRに紐づいているドキュメントorチャットというたどり方が案外近道になることも！？

実装方法のキャッチアップ

キャッチアップ材料	相性
ドキュメントツール	◯
ソースコード	◯
PR、コミット	◎
テキストコミュニケーションツール	◯
ヘルプページ	×

「表にこちらのアイテムを追加してください」
「こちらの機能にもログ出力の処理を追加してください」
など過去に前例がある機能実装の場合は、参考PRを探すのがオススメです！
過去の参考PRはどのファイルを弄る必要があるのかなどを理解するのに役立ちます👍

こちらも背景のキャッチアップと同様にGitLensなどを駆使して参考PRを探すのがオススメです！

まとめ
過去の参考PRを探そう！

その他

キャッチアップをする際に、自分の分報チャンネルに「分かったこと」「分からないこと」をどんどん書いていくのが良いと思います。（Working Out Loud（大声作業））
自分の考えをアウトプットし続けていると、他の人から反応をもらえることがあり、その際にキャッチアップが進むことも多々あります。

また、「分かったこと」「分からないこと」もポーネグリフになり、将来別の誰かを助けることがあるかもしれませんので、キャッチアップした内容をどんどんアウトプットしていくことは良いことが多いです

まとめ
キャッチアップした内容はどんどんアウトプットしよう！未来の誰かを救うかも？

おわりに

新しい会社に入社したけど最初の数ヶ月は分からないことだらけでしんどい…と感じているエンジニアの方々の参考になればと思います！
皆さんのおすすめのキャッチアップ方法があれば是非教わりたいです！🙏
最後まで読んでいただきありがとうございました！🙏