はじめに
本連載は、WANTEDLY TECH BOOK 2から抜粋し、再編集したものになります。今回のテーマはGitHubによるドキュメントの活用術です。
皆さまはドキュメントの管理はどうされていますでしょうか。一口にドキュメントといっても、議事録のような打ち合わせの内容を書き留めたものから、システムの仕様を文書や図で書き留めたもの、時にはビッグデータのスナップショットなど、さまざまなものがあります。
それらの管理がバラバラにになったままだと、意図的に共有しない限り、他のメンバーが存在に気づくことすらできず、せっかくのドキュメントも活用できません。Wantedlyでは、ドキュメントやそれに伴うコミュニケーションをGitHubのIssueやPR（Pull Request）にひも付けた形で行うことで、この問題に対処しています。
WHYとWHAT
WantedlyのGitHub上でIssueやPRを作る際はWHYとWHATを必ず書きます。「何故（WHY）そのIssueが作られたのか」「何（WHAT）をしたら解決なのか」を明確にしなければ、どれだけのコストをかければいいか、そもそもコストをかけるべきか判断ができません。
もちろん全てのIssueやPRに書くことは手間であるため、親となるものにリンクのみを書いて省略することはあります。
情報の探し方と残し方
新しいチームに参加したときはチームを把握するために、まずドキュメントを読むと思います。その際、自分がどうやって情報を探すかを考えると、同時にどうやって情報を残せばいいかが見えてきます。
IssueやPRの間でのリンク
GitHub上のIssueやPRはそれらの間でリンクを張ることができます。ドキュメントを残すときは関係があるものの間でリンクを張り巡らせていくことで、後続の人たちが探しやすいようにします。
「どのようにリンクを張ればいいか」、それは仮に自分がドキュメントを探す際、どのように探すかを考えると見えてきます。
例えばトップダウンで探す場合は、大きなタスクにはどこかしらに指針となるIssueがあると考え、まずはそれを探し、そこから自分の担当に関係があるものを手繰るでしょう。逆にボトムアップで探す場合は、個別のIssueやPRから逆にリンクを手繰るでしょう。これが実現できるリンクの張り方をすればいいわけです。
これを実現するためのリンクをGitHubでは非常に簡単に作ることができます。URLを張るだけで、GitHubがいい具合に表示してくれるからです。GitHub上のリンクは同一リポジトリだけではなく、GitHub上の他のリポジトリともリンクを張ることができます。
チームが業務を進める上で、1つのリポジトリだけで完結させることは事実上無理であるため、異なるリポジトリの複数のIssueやPRをリンクさせることで対応しています。
同一のリポジトリであれば＜#記号＋番号＞で、異なるリポジトリの場合は＜リポジトリ名＞/＜番号＞でも張れます。例えば次のように書くとブラウザ上で見やすく表示してくれます。
## WHY & WHAT wantedly/yashima/issues/456 にて報告されている不具合です。 #410 のPRに起因しています。
例えばWantedly Peopleはプロジェクト名が”yashima”なのですが、下図のように大きく3つのリポジトリから構成されていました。
この中のyashimaリポジトリにはプロダクトの直接的なコードは含まれておらず、主に仕様やドキュメントを管理するものになっています。AndroidアプリやiOSアプリ、APIなどのバックエンドを巻き込んだタスクを行う際は、yashimaリポジトリにIssueを作り、個々の担当で必要なものはそれぞれのリポジトリにIssueを作ってリンクを張るようにします。
こうしておけば後から情報を探すときも、トップダウンとボトムアップ、いずれの方法でも情報が探せるようになります。
