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

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

キャッチアップしてもらうときの配慮

　新しいIssueやPRを作ったときに関係するメンバー全員が気づくと限らないため、その場合は関係するメンバーにメンションすることで参加者に巻き込みます。すると、相手のNotificationsに表示されるのでキャッチアップしてもらえます。

　しかし、通知が多すぎると全てを把握できず、抜けが発生するようになります。連携する場合は相手がキャッチアップしやすい形にすることが大事です。それは自分自身が連携する側であるとともに、連携される側でもあるからです。つまり、自分自身のためにもなります。

連携は相手がキャッチして初めて成立する

　情報の重要度は内容によってマチマチですが、連携は相手がキャッチできて初めて成立します。

　Issue上のメンションは気軽にできる連携ですが、重要なものは社内チャットでも直接声をかけるだけでもいいので、伝わったか確認しましょう。

　「メンションしたのだから気づかない人が悪い」とも考えられますが、往々にして困るのは自分を含めたチーム全体なので、思いやりを持って伝えることが大事です。自分がメンションされた側のときも、伝わったことを意思表示するといいでしょう。

　IssueやPRにコメントを書くという手もありますが、下図のようにreactionを使ってアイコンを返すだけでも、メンションした側の安心度が変わってきます。

reactionの表示

監視するものは減らしたい

　Wantedlyでは全社的にGitHubを起点としてプロジェクトを進めていますが、組織によってはRedMineやTrelloなどを使っているところもあるでしょう。

　たくさんのものを監視するとなると、見落としによる抜けが発生する確率が上がるため、どれか1つを正として進めるといいでしょう。

　WantedlyではメンバーがNotificationsを見ているため、そのことを意識して連携するようにします。

情報は多すぎると読まれない

　ネットスラングですが「TL;DR（Too Long; Didn't Read）」という表現があります。議論が発生して長くなったIssueは、そのままでは全部読まないと結論がわからず、誤解される可能性もあります。

　例えば、議論はアプリ実装者間で行うものの、最終的な仕様をAPI実装者に伝えるとき、長いIssueを見ただけで仕様をくみ取るのは困難です。これを避けるため、Issueをクローズするタイミングなどで「決めたこと」をまとめるようにしましょう。

決めたことを書く

連携する際の重要度

　メンションするときにcc（carbon copy）やFYI（for your information）という理由が付加されていると、メンションされた側がその重要度を意識できるため、心理的な負担を低減することができます。

タスクの進捗はわかりやすくする

　IssueやPRのコメントにはチェックボックスを作ることができます。下図のようにやるべきことをチェックボックスにしておくと、他のメンバーが見たときも何が残っているか一目でわかるようになります。

checkboxで何が残っているかハッキリさせる

1週間後の自分は他人

　「ドキュメントやコードは他の人が見てもわかるように」というのはよくいわれることですが、具体的にどうすればいいのかをイメージできる人は少ないと思います。

　筆者はこれについて「1週間後の自分が見て思い出せること、誤解しないこと」を意識して書くようにしています。自分で作った罠に自分で嵌まった経験から覚えたことで、自分が嵌まるような罠は他の人も同じように嵌まるからです。

　「誤解した人が悪い」とも考えられますが、往々にして困るのはチーム全体なので、「誰が悪い」などではなく、他の人が誤解しないように、思いやりを持って書くことが大事です。

おわりに

　GitHubをドキュメント管理の中心におくことで、作成されたドキュメントが活用されない問題を解決する方法を説明しました。

　簡単にいえば、IssueやPRだけでなく、外部のサービスも含めてリンクを張り巡らし、それをチームメンバー間で必要な人に必要なタイミングでメンションし合うことに尽きます。もっとも、それらはチームメンバー間の細かな思いやりで、チームによってそれぞれ異なった独特の文化を形成するものでしょう。

　この記事を読んでくださった方が自分たちのチームに取り込み、新しい文化や、より良いアプローチを考えて実践してもらえれば幸いです。

　それでは皆さん、GitHubで良いプロダクト作りを。