GitHubを使ったキャッチアップしやすいドキュメントの管理方法

開発現場からお届け！ Wantedlyのプロダクトを育て、支える技術 第3回

　Wantedlyの社内ではその場その時でチームメンバーがもっとも効率よく働けるものを選択して利用します。この連載では実際の開発で取り組んでいる技術や手法を、実務に使える形でお伝えしていきます。今回はプロダクトを運営していく上で日々作られるドキュメントを、GitHubを使って埋もれず無駄にならないように管理していく方法をご紹介します。

はじめに

　本連載は、WANTEDLY TECH BOOK 2から抜粋し、再編集したものになります。今回のテーマはGitHubによるドキュメントの活用術です。

　皆さまはドキュメントの管理はどうされていますでしょうか。一口にドキュメントといっても、議事録のような打ち合わせの内容を書き留めたものから、システムの仕様を文書や図で書き留めたもの、時にはビッグデータのスナップショットなど、さまざまなものがあります。

　それらの管理がバラバラにになったままだと、意図的に共有しない限り、他のメンバーが存在に気づくことすらできず、せっかくのドキュメントも活用できません。Wantedlyでは、ドキュメントやそれに伴うコミュニケーションをGitHubのIssueやPR（Pull Request）にひも付けた形で行うことで、この問題に対処しています。

WHYとWHAT

　WantedlyのGitHub上でIssueやPRを作る際はWHYとWHATを必ず書きます。「何故（WHY）そのIssueが作られたのか」「何（WHAT）をしたら解決なのか」を明確にしなければ、どれだけのコストをかければいいか、そもそもコストをかけるべきか判断ができません。

　もちろん全てのIssueやPRに書くことは手間であるため、親となるものにリンクのみを書いて省略することはあります。

WHYとWHATをリンクで省略

情報の探し方と残し方

　新しいチームに参加したときはチームを把握するために、まずドキュメントを読むと思います。その際、自分がどうやって情報を探すかを考えると、同時にどうやって情報を残せばいいかが見えてきます。

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つのリポジトリから構成されていました。

Wantedly Peopleの3つのリポジトリ

　この中のyashimaリポジトリにはプロダクトの直接的なコードは含まれておらず、主に仕様やドキュメントを管理するものになっています。AndroidアプリやiOSアプリ、APIなどのバックエンドを巻き込んだタスクを行う際は、yashimaリポジトリにIssueを作り、個々の担当で必要なものはそれぞれのリポジトリにIssueを作ってリンクを張るようにします。

　こうしておけば後から情報を探すときも、トップダウンとボトムアップ、いずれの方法でも情報が探せるようになります。