/note/tech

スケールする組織を支えるドキュメンテーションの技術を”GitLab Handbook”から学ぶ

1. WikiではダメでGitリポジトリじゃないとスケールできないと理解する

(中略)

Wikiでは、ページの複数の部分や複数のページにまたがるような提案をすることができない。また、作業者とレビュワーの役割を分けることができない。また、提案を取り込むべきか取りこまないべきかの議論もできない。そのため、ハンドブックはリファクタリング不能な状態に陥る。

2. ハンドブックファースト思想を貫く

GitLabではハンドブックファースト思想を貫いている。ハンドブックは常に最新であり、中に重複がないように書かれている。いわゆるSingle Source of Truth性があるように保たれている。そのため、Wikiでしばしば見られるような、複数の文書が同じ内容を示しており、それらが違いに矛盾しているような状況は見られなくなる。

さまざまな議論をSlackやメールや、インターナルなプレゼンテーションを行う場合に、該当のハンドブックへの参照URLつけることを常に試みることが奨励されている。わざわざ何かを説明する時にプレゼンテーションスライドを作るのではなく、ハンドブックで代用することが奨励される。

3. 内容にアクセス可能にする

ハンドブックは4000ページ弱あり(2020年現在)、その全てを把握できている人はいない。このテキストの山を活用するためにGitLabでは検索機能をつけることを推奨している。GitLabでは第一にAlgoliaというSearchのクラウドサービスを利用している。第二に、PublicにHandbookを公開することで、Google検索にHitするようにしている(これは真似できないかも)。