GitLab におけるハンドブックの使い方

運用の流れ

1. (プロセス上の) 問題が発生します。多くの場合、Issue やチャットで浮上します。
2. ハンドブックへのマージリクエストという形で提案を作成します。
3. マージされたら、MR またはコミットの差分へのリンクを添えて変更を周知します。重大なものは #whats-happening-at-gitlab Slack チャンネルに投稿します。中程度のものは可視性を高めるため #handbook チャンネルに、変更の一行要約を添えて投稿します。元になった Issue があれば、差分へのリンクを残してクローズします。

ミーティング中に提案をリアルタイムで編集したい場合には、Google ドキュメントを使う必要があります。その際は、ミーティング後にこの内容が移される先となるハンドブックページの URL を、一番上の項目にしてください。

ハンドブックファーストの理由

何かを実行する前にハンドブックに書き出すのは、初期には時間がかかるかもしれません。どこに変更を入れるかを考え、既存のコンテンツと統合し、適切な土台を持たせるためにハンドブックを追記・リファクタリングする必要があるかもしれないからです。しかし長期的には時間の節約になり、このコミュニケーションは、私たちの組織を拡大させ、変化に適応させ続けるために不可欠です。

このプロセスは、ソフトウェアのテストを書くことに似ています。(提案中の) 変更は、ハンドブックへの変更を通してのみ伝えてください。プレゼンテーション、メール、チャットメッセージ、その他の媒体を変更内容の伝達に使わないでください。これらの他の形式は発信者にとっては便利かもしれませんが、受け手にとっては文脈や、他の影響を受け得るプロセスへの波及を理解するのが難しくなります。

「ハンドブックファースト」 のメンタリティを持つことで重複がなくなり、ハンドブックは常に最新の状態に保たれ、他の人々もより貢献しやすくなります。

私たちは単なる「ハンドブックファースト」にとどまらず、「公開ハンドブックファースト」でもあります。情報が 内部限定 の場合は Internal Handbook に載せるべきですが、公開可能 なものはデフォルトで公開ハンドブックに載せます。これにより、SAFE に共有できる情報は誰もが参照できるようになります。これは透明性・効率性・結果を含む GitLab の 価値観 を支えます。また、本来公開されるべき情報が Internal Handbook にとどまることや、矛盾・重複した情報源が生まれることを防ぎます。

INSEAD のケーススタディインタビュー (上記動画) でオールリモートに関する課題について質問されたとき、GitLab 共同創業者の Sid Sijbrandij は次のように答えました。

最大の問題は、GitLab がハンドブックファーストで動けないことです。私たちには、協働し、新しい人をオンボードし、集合的に思考することを可能にする素晴らしいハンドブックがあります。

ところが、ハンドブックに変更を加えて周知するというのは直感に反します。何か変更を伝えたいとき、人々のデフォルトは Slack メッセージを送ったり、メールを送ったり、プレゼンをしたり、ミーティングで話したり — ハンドブックを変更すること以外の何か をすることです。

その方が本人にとっては早い。他のどの形式でも、ハンドブックを変更するより早いのです。ハンドブックを変更する場合、まずハンドブックの該当箇所を探し、ときには自分の変更が収まるようにハンドブックを調整し、技術的なプロセスと 1 回か 2 回のレビューを経て、デプロイを少し待たなければなりません。

他のどの選択肢よりも遅いのです。しかし、そうすることで、後から変更を加える人々がその上に積み重ねていけるようになります。余分な時間をかけるとき、それは次のものの土台を築いているのです。

私はこれをレンガ積みのようなものだと考えています。あらゆる情報の断片はレンガです。GitLab にはよく構造化された一軒の家があり、全員がその一軒の家に積み上げていきます。私たちは建て方にかなりこだわるので、その家は強固な土台を持ち、非常に高くまで積み上げることができます。

他のすべての会社では、レンガを人々の手に投げ渡しています。全員が日々レンガを受け取り、それを自分が内部で建てている家に積み上げなければなりません。彼らは物事を忘れ、不明瞭になっていきます。どこにレンガを置けばよいかという文脈がないため、大量の文脈を作り出さなければなりません。

その結果、見た目も異なり、どれも少しずつ傾いていて、上に 1 つレンガを積むと下から 1 つ飛び出すような、千軒の家が出来上がってしまうのです。 — GitLab 共同創業者 Sid Sijbrandij

このハンドブックの範囲

ハンドブックは、GitLab のチームメンバーが仕事をするうえで必要なコンテンツに焦点を当てます。その他の有用なコンテンツについては、外部の情報源にリンクします。

• より広いコミュニティからのコード貢献にも関係するドキュメント (たとえば コントリビュート や コードレビューガイドライン など) は、チームメンバー限定のハンドブックではなく、GitLab プロジェクトに置くべきです。
• ユーザー向けの会社情報については、メインのマーケティング ウェブサイト や ブログ があります。
• ハンドブックは現在および将来の GitLab チームメンバーに関する事柄のためのものです。GitLab のユーザーに関するものは、GitLab ドキュメント、GitLab Development Kit (GDK)、CONTRIBUTING ファイル、または PROCESS ファイル に文書化してください。

ハンドブックのガイドライン

以下のガイドラインに従い、また他の人にも思い出させてあげてください。

日々のガイドの使い方

1. このハンドブックのほとんどのガイドラインは、特に明記がない限り、絶対的なルールというより助けとなることを意図しています。ハンドブックの全部を知らないからといって、何かをすることを恐れないでください。全部を知っている人は誰もいません。これらのガイドラインを他の人に思い出させるときは、優しく伝えてください。たとえば「問題ありませんが、次回はハンドブックの以下のガイドラインも考慮してください」のように。
2. 質問をして誰かがハンドブックへのリンクで答えたとしたら、それは情報を提供して助けたいからです。答えが文書化されていることを誇りに思っている場合もあります。ハンドブックを全部読んでおくべきだったという意味ではありません。ハンドブック全部を知っている人はいません。
3. チームメンバーに質問する必要があるとき、コミュニティの大多数もその答えを知らない可能性が高いことを認識してください。必ず答えを 文書化 して、その情報をコミュニティ全体に放射してください。質問に答えた後、どこに文書化すべきか、誰がそれをやるかを議論してください。「誰がこれを文書化しますか？」と尋ねることで、他の人にこのリクエストを思い出させられます。
4. チャットで何かを議論するときは、関連があれば常に URL にリンクするようにしてください。たとえば、質問対象のドキュメントや、答えてくれたページなどです。他の人にもこのことを、「リンクを貼ってもらえますか？」と尋ねることで思い出させられます。
5. ハンドブックは、私たちがやりたいこと、正式にはこうすべきこと、数ヶ月前にやったことを書くものではないことを覚えておいてください。それは私たちが今やっていることです。 プロセスを本当に変えるためには、必ずハンドブックを変更してください。プロセス変更を提案するには、ハンドブックへのマージリクエストを作成します。ハンドブックの変更提案に他のチャネル (メール、Google ドキュメントなど) を使わないでください。
6. ハンドブックはプロセスそのものです。「process」「policies」「best practices」「standard operating procedures」といった名前のセクションは、より深い問題のサインです。これは、プロセスの散文的な記述と、同じプロセスの番号付きリストでの記述が重複していることを示している可能性があり、それらは 1 つの記述に統合すべきです。
7. 何かを伝達するときは、メール/チャットなどにテキストを含めるのではなく、常に ハンドブック の関連する (かつ最新の) 部分へのリンクを含めてください。他の人にもこのことを、「ハンドブックの該当箇所にリンクを貼ってもらえますか？」と尋ねることで思い出させられます。
8. ハンドブックの変更を把握し続けたい人は、#handbook チャンネルに自由に参加できます。

プレゼン資料を作らず、ハンドブックをスクリーンショットする

プレゼンテーションは、役員会プレゼンのような短命なコンテンツには最適です。リーダーシップトレーニング のような エバーグリーンなコンテンツ は、ハンドブックを基にするべきです。これは ハンドブックファーストで働く ことの重要な要素です。

エバーグリーンなコンテンツのプレゼンテーションを作成する際は、内容をコピー&ペーストしたり (またはハンドブック情報を模倣するようスライドを個別に整形したりする) のではなく、ハンドブックのスクリーンショットを撮り、表示されているページへのリンクを提供してください。このアプローチは 非同期コミュニケーションへの傾向 を示すものであり、以下がその理由です。

1. ハンドブックとプレゼン資料の両方を更新する必要がなくなり、労力が節約できる。ハンドブックが準備作業の一環として確認・改善されるため、追加作業にならない。
2. ハンドブックが最新の状態に保たれるため、人々が古い情報をプレゼンから見ることがなくなる。
3. スクリーンショットを見せることで、コンテンツがハンドブックにあり、そこで最新に保たれていることを人々に確認させられる。
4. 人々がハンドブックの構造に慣れ、後から関連するハンドブックのセクションを見つけやすくなる。
5. ハンドブック上にあるので、誰もがコンテンツに貢献できる。
6. コンテンツが私たちの他のプロセスと統合され、文脈の中で表示される。
7. プレゼンテーションよりもウェブページの方が、検索やリンクがしやすいため、はるかに多くの人々にコンテンツが消費される。
8. 世界中の他の組織や学生に、私たちがどうやっているかの例を示すことで、彼らを助けることになる。
9. ハンドブックを使う利点 も参照してください。

プレゼンテーションの見栄えは劣るかもしれませんが、メリットの方がその懸念を上回ります。

同期的なプレゼンテーションが必要な場合は、スライドプレゼンよりも、画面を共有してハンドブックのライブページを見せることをデフォルトにしてください。

ハンドブックの検索

すべての GitLab ハンドブックのページには、ページ上部付近に検索用の入力フィールドがあります。 ハンドブックをより速く、より効率的に検索するヒントは GitLab をプロのように検索する ページを参照してください。

プロセスを変更・定義する方法

1. ガイドラインやプロセスを変更するには、マージリクエストという形で 編集を提案 してください。

2. 変更を素早くマージしてもらうためには、マージ権限を持つ適切なチームメンバーに依頼しているかを確認してください。責任者が誰か分からない場合は、該当プロジェクトの CODEOWNERS ファイルを参照し (また追加し) てください。

   • たとえば CMO (Chief Marketing Officer) スタッフメンバーは自分の機能に固有のマージリクエストを承認できますが、マーケティング横断的なマージリクエストは CMO が承認します。CEO 付きチーフオブスタッフ/CEO は、GitLab の 価値観 ページのように会社横断的に影響するマージリクエストを承認します。

3. マージされた後は、必要に応じて #whats-happening-at-gitlab Slack チャンネルに投稿できます。他の人にもこのことを、「ハンドブックへのマージリクエストを送ってもらえますか？」と尋ねることで思い出させられます。

4. ハンドブックのレイアウトを大幅に変更する際は、その MR で直接影響を受ける レビューアプリの特定ページへのリンクを残してください。リンクとあわせて、MR の説明にできる限り多くの情報を含めてください。そうすることで、差分を見なくても MR の目的を全員が理解できるようになります。

5. ハンドブックの変更を追いかけるのは大変なことがあるので、コミットメッセージのガイドライン に従ってください。特にマージリクエストのタイトルに注目し、誰もが MR の内容を素早く理解できるようにしてください。

6. プロセス変更の伝達には、マージ済みの差分 (変更前と後を示すコミット) へのリンクを使ってください。議論やフィードバックを目的として変更を伝達しているのであれば、未マージの差分 にリンクしても構いません。プロセスを先に変えて、文書化を優先度の低いタスクとして扱わないでください。後で文書化する計画は、変更を伝達するための二重作業と古い文書化を必ず招きます。他の人にもこのことを、「先にハンドブックを更新してもらえますか？」と尋ねることで思い出させられます。

7. 可能なときは、プロセス変更を反復的に導入してください。マージリクエストを小さく作る ことでハンドブックに貢献することが重要です。これにより、プロセスの想定される対象者の中での採用が進みやすくなります。不必要に大きく、トップダウンで、破壊的なプロセス変更は避けたいところです。こうしたプロセス変更は DRI から権限を奪い、結果ではなくプロセスに人々の意識が向いてしまう原因になります。

8. 他のすべてと同様に、私たちのプロセスは常に流動的です。すべては常にドラフトであり、最初のバージョンもハンドブックに入れるべきです。ハンドブックへの変更を提案する場合は、可能な限り Issue を飛ばしてマージリクエストを提出してください (Issue の説明で提案するよりも、マージリクエストで提案するほうが望ましい)。マージリクエストでは変更によって影響を受ける人々をメンションしてください。多くの場合、マージリクエストは提案された変更を見られるため、コラボレーションがしやすくなります。

9. 何かが限定的なテストであれば、ハンドブックに追加し、その旨を注記してください。テスト終了後、注記を削除し、すべてのケースが新しいプロセスを使うようにします。

10. GitLab の内外で誰かが良い提案をしたら、ハンドブックに追加するよう招待してください。関連するページとセクションの URL を送り、できない場合は代わりに行うと申し出てください。本人に変更を作成・送信してもらうことで、その変更が実現し、その人の知識が反映されます。

11. マージリクエストを提出したら、素早くマージされるようにしてください。単一の小さな変更を素早く行うことで、あなたのブランチが master から大きく遅れてマージコンフリクトが生まれることを防げます。更新は同日中に作成してマージすることを目指しましょう。マージリクエストで人々をメンションするか、Slack で連絡してください。既存の改善の上に乗せる大きな改善の提案を受けた場合は、別に実施することを検討してください。Issue を作成し、既存の MR をマージして、新しいマージリクエストを作成します。

12. コンテンツを移動する必要がある場合は、移動だけを行うマージリクエストにしてください。整理・要約・拡張したい場合は、移動の MR がマージされた後に行ってください。その方がレビューがはるかに簡単になります。

13. ハンドブックプロセスの「なぜ」を追加する ようにしてください。ビジネス上の目標は何か、このセクションのきっかけは何か。「なぜ」を追加することで、その「なぜ」が変わったかを評価でき、将来プロセスを変更しやすくなります。

14. エンジニアリングワークフロー にプロセスを追加・変更するときは、X ヶ月先にレトロを予定することを検討してください。レトロは新しいプロセスの 効果を検討 し、さらなるイテレーションが必要か、あるいは削除できるかを判断する機会になります。

追加プロセスを導入する際の考慮事項

必須ではありませんが、新しいプロセスの導入後 X ヶ月先に非同期レトロ用の MR/Issue を予定しておくと役立つことがあります。

成功とは何かを判断するため、改善の目標と期間を特定することを検討してください。レトロ MR/Issue を使って期待値を透明に伝えるとともに、新しいプロセスをイテレーションしたり削除したりする手段にもできます。

レトロ MR/Issue の作成は、以下を考え抜く機会です。

1. この新しいプロセスで何を達成したいのか？
2. 新しいプロセスの効果を測るために使える指標はあるか？
3. 新しいプロセスの結果として、ロールバックを促すような成り行きはあるか？

レトロそのものは、以下を文書化する機会です。

1. プロセスの参加者は、物事の進み具合をどう感じているか？
2. 新しいプロセスに関連して生じた追加コストは何か？
3. 新しいプロセスに予期せぬ副作用はあったか？
4. 参加者は、新しいプロセスで発生したコストを軽減する方法、またはより一般的な改善の提案を持っているか？

情報アーキテクチャ

唯一の信頼できる情報源 (SSoT)

重複を排除し、Single Source of Truth (SSoT) を持つために、情報アーキテクチャを考えてください。同じ内容を繰り返すのではなく、相互リンクしてください (双方のテキストにもう一方へのハイパーリンクを張る)。コンテンツをコピーした場合は、元の場所から削除して新しいコンテンツへのリンクに置き換えてください。重複したコンテンツは、複数箇所でのコンテンツ更新が必要になり、古いコンテンツがどこにあるかを覚えておく必要も生じます。唯一の信頼できる情報源があれば、単一のシステムにのみ格納されます。 関連するアイテムがある場合 (ハンドブックの他の場所、ドキュメント、Issue など) は、必ず相互リンクするようにしてください。

記録システム (SoR)

記録システム (SoR) は、所与のデータ要素や情報の権威あるデータソースです。記録システムが唯一の信頼できる情報源を兼ねることはあり得ますが、単に記録システムであるというだけで、それが唯一の信頼できる情報源であるとは直接には意味しないことに注意してください。

機能と結果による整理

ハンドブックは 機能と結果で整理 されており、すべての項目に場所とオーナーがあって最新に保たれるようにしています。

• この階層を守ることは不可欠で、会社のトレーニング資料 (オンボーディング資料、ハウツーなど) や動画、その他のドキュメントのために別の構造を維持してはいけません。
• この階層を守ることは、ときとして直感に反します。 何年もかけて、コンテンツを文脈の中に保つことが、将来の更新時に一貫性を保つのに役立つと学んできました。
• 視点の転換が望まれる場合もあります。 そうしたケースでは、ハンドブックの該当セクションにリンクし、コンテンツ自体を含めないでください。 例として オンボーディングテンプレート (社内向け) を参照してください。 あるいは、定義を重複させずに performance indicator にリンクしている Key Performance Indicators の一覧も例になります。

スタイルガイド

ハンドブックを編集する 前に、以下のスタイル案内と ライティングスタイルガイドライン を読んでください。

ハンドブックのページ

ハンドブックのページは短く簡潔にしてください。冗長な部分を排し、できる限り短い言葉で要点にたどり着きます。 新入社員から挙がる最大の課題は、オンボーディング中に取り込むべき情報の膨大さであることを覚えておいてください。

構造化されていないコンテンツを避ける

• Learning Playbooks、FAQ、リンク集 (クイックリンクなど)、リソースページ、用語集、コース、動画、テスト、プロセス、標準作業手順書、トレーニング、ハウツーといったフォーマットに基づく、構造化されていないコンテンツを避けてください。 これらは最新に保つのが非常に難しく、機能と結果による整理とも相性が良くありません。たとえば、Contract Negotiation Playbook ではなく Contract Negotiation Handbook と呼んでください。
• 代わりに、答え、リンク、定義、コース、動画、テストは最も関連のある場所に置いてください。 記述的な見出しを使って、コンテンツを検索しやすくしてください。
• とはいえ、ハンドブックの中では、単一ページの中であっても適切な場面で フォーマット を混在させてください。 複数のフォーマットを活用することは価値があり、人によっては特定のフォーマットを好むこともあります。
• ページが様々な種類・フォーマットのコンテンツを埋め込んだ場合の見た目ではなく、機能と結果ごとの整理 にのみ気を配ってください。
• 注記: FAQ の弱点 として、質問は偏った、あるいは誘導的な形で尋ねられがちです。可能であれば、事実は事実として書いてください。

見出しを惜しまず使う

ページに 3 つ以上の見出しが含まれる場合 (特に 1 画面を超える場合) は、この MR の 6 〜 10 行目 をコピーすることで自動生成の目次 (ToC) を追加してください。 見出しはセンテンスケース (文頭のみ大文字) にします。ALL CAPS や TitleCase は使わないでください。 見出しの後には 1 行の空行を残します。これは 標準では必須ではありません が、私たちの慣習です。

貢献可能な図を使う

画像アップロードや貢献しにくい図よりも、貢献可能な図を優先してください。これにより、他の人が変更を提案したり貢献したりしやすくなります。Markdown で使える図のオプションには Mermaid や PlantUML があります。

ハンドブックファーストのコンピテンシー

オールリモートで非同期の組織においては、各チームメンバーがハンドブックファーストを実践する必要があります。ハンドブックファーストであることの意味については、このページの ハンドブックファーストの理由 セクションを参照してください。

チームメンバーとしてのハンドブックファーストのスキルと振る舞い:

• ハンドブックに積極的に貢献する。
• マージリクエストから始める
• 質問に答える際にハンドブックから情報へのリンクを提供し、ハンドブックに情報が存在しない場合はそれを追加する。
• どの情報が内部限定かを理解したうえで、公開できるすべての情報は公開ハンドブックに置く。

ピープルリーダーとしてのハンドブックファーストのスキルと振る舞い:

• 自分のチームとその他の人々がハンドブックファーストであることに対して説明責任を負わせる。
• 内部限定でない情報について、公開ハンドブックファーストであることにリーダーシップを発揮する。
• 新しいチームメンバーやマネージャーに、ハンドブックをリソースとして活用する方法を教える。
• ハンドブックファーストであることの模範となる。

運用管理

ハンドブック (公開ハンドブックと Internal Handbook) を最新の状態に保つことは、各部門とチームメンバーの責任です。ハンドブックのコンテンツは正確であるべきで、ガイドライン に示された同じフォーマットに従います。誰にマージリクエストを送るべきか、またはハンドブックに関する支援については、#handbook Slack チャンネルに気軽にご連絡ください。

ハンドブックに直接コミットする権限が必要な場合は、New Access Request Issue を提出し、アクセス承認のプロセスに従ってください。該当するハンドブックの ‘Maintainer’ ロールをリクエストしてください。

マージ権限のガイドライン

MR をマージするには、該当するハンドブックプロジェクトへの developer アクセス が必要です。すべてのチームメンバーはデフォルトで developer アクセスを持っているはずです。このページには、マージの際に念頭に置くべきいくつかのヒントとガイドラインが記載されています。

自信を持ってマージする

パイプラインを通過したあらゆる変更は、ハンドブックを壊してしまうのではと心配することなく、自信を持ってマージしてよいと感じるべきです。パイプラインのテストは主要な問題を捉えるように設計されています。ハンドブックの各プロジェクトは、パイプラインが通過するまで変更をマージできないように構成されています。万が一、ハンドブックを何らかの形で壊すコードがマージされた場合は、ハンドブックチームへの問題報告 の手順に従ってください。

merge immediately を使わない

merge immediately 機能を 使わない でください! たとえ MR が重要で時間的に切迫していても、この機能を使うと他のすべての人に多大な痛みを生じさせます。この機能は、重要な公開情報をできる限り迅速に公開しなければならない場合にのみ使用すべきで、PR または Legal による承認を得るべきです。PR または Legal の承認がない場合は、この機能を使わないでください。

この背景にある技術的な理由は以下の通りです。

• デフォルトブランチのパイプラインを高速にしたいからです。これにより、変更がデプロイされ本番サイトに反映されるまでの時間を最小化できます。
• これを実現するため、デフォルトブランチではテストやリンターを実行しません。これらは長時間のジョブであり、高速デプロイの妨げになるためです。
• 代わりに、マージトレイン に頼り、すべてのマージリクエスト変更がマージを許可される前に、必要なテスト/リントジョブをすべて通過しているかを保証します。
• したがって「merge immediately」を使うと、テスト/リントジョブは一切実行されず、問題が混入した場合はデフォルトブランチが壊れる結果になります。
• これは 以降デフォルトブランチから新しい MR を作成するすべての人が、自分の責任ではない混乱したパイプライン失敗を経験する ことを意味し、この状況が発見され、修正がデフォルトブランチにマージされるまで続きます。

いつ承認を得るか

自分のページへの小さな変更のたびに承認を求められるのは煩わしく感じるかもしれませんが、適切な承認なしにハンドブック内のポリシーや手順を誰かが変更してしまうと、強い負の影響が生じ得ます。承認を求めるかは自分の最善の判断を使ってください。

合理的と思える場合には、硬直性よりも責任 を実践してください。ページオーナーがあなたの変更を喜ぶと期待されるときは、承認なしにマージしてしまいましょう。変更を知らせるため、常にコードオーナーに @メンションのコメントで通知してください。彼らは、ページがより良くなったことに喜び、レビューと承認に時間を無駄にせずに済んだと感じるでしょう。万一それが改善にならなかった場合は、サインオフよりもクリーンアップ を実践します。

適切な場合、たとえば以前は内部限定だったドキュメントを公開する場合などは、マージ前に 承認機能 を使って コードオーナー の承認を得てください。

誰が承認できるか

ハンドブックページのオーナーは、ハンドブックの Web 版でページを開き、編集中のページの右側にある Maintainers セクション (ブラウザウィンドウが小さい場合は隠れている可能性あり) に誰がいるかを見ることで特定できます。

一部のページでは Maintainers セクションが空になっています。これは、ページが個人ではなくグループによって保守されているためです。どのグループや個人がページを保守しているかを確認するには、該当リポジトリの CODEOWNERS ファイル (たとえば ハンドブックの CODEOWNERS) を参照してください。

ページのコードオーナーは、マージリクエストの approval セクション を見ても確認できます。

ページのコードオーナーは、そのページの DRI であり、ハンドブックに何が掲載されるかの最終決定権を持ちます。迷ったら、彼らのページを変更する前に DRI の許可を得てください。DRI が C レベルの人でも心配しないでください。あなたが個人貢献者であっても、MR を割り当てることができます。これは、私たちが 直接コミュニケーションする ことを好むからです。

変更は同僚にレビューしてもらう

タイポのような小さな変更を除いて、マージする前には常に別のチームメンバーに変更をレビューしてもらってください。

広範な権限

Maintainer であることは、単にマージする能力を超えた多くのアクセス権を与えます。権限の完全な一覧 はドキュメントで確認できます。プロジェクトの幅広い設定や構成にアクセスできるようになることを念頭に置いてください。設定の調整や構造的な変更はしないでください。

他者に maintain アクセスを付与する

アクセスリクエスト なしに maintainer アクセスを付与しないでください。Maintainer として、他者に maintainer アクセスを付与する能力を持っていますが、適切な承認を集め、必要なドキュメントを作成するアクセスリクエストのプロセスに従わずに行わないでください。

Issue とマージリクエストの説明テンプレート

Issue とマージリクエストの 説明テンプレート は、各プロジェクトで .gitlab/issue_templates と .gitlab/merge_request_templates ディレクトリにそれぞれ配置されており、新しいマージリクエストで編集・変更できます。

現在の承認者一覧は .gitlab/CODEOWNERS を参照してください。

Internal Handbook

どこにあるか？

• Internal Handbook Project
• Live Website

なぜ Internal Handbook があるのか？

会社として、私たちは デフォルトで公開 ですが、公開では話せないこともあります。Internal Handbook は、チームメンバーが内部情報を共有できる場です。内部限定 と見なされ ない ものはすべて、GitLab の 公開ハンドブック に置くべきです。limited access のものは、Internal Handbook がすべてのチームメンバーからアクセス可能であるため、Internal Handbook に追加すべきではありません。

このハンドブックを使うプロセス

非公開 カテゴリに分類されるもののみを Internal Handbook に追加してください。それ以外はすべて、公開会社ハンドブック に追加すべきです。

Internal Handbook グループへのアクセス

すべてのチームメンバーは、オンボーディング時のベースラインアクセスとして Okta 経由で Internal Handbook にアクセスできます。Okta ダッシュボードにログインし、GitLab Internal Handbook タイルをクリックしてください。まず Okta で認証する必要があります。

Internal Handbook の使用に関する質問

• Internal Handbook と公開ハンドブックのどちらに入れるべきかについての質問？ safe framework を参照するか、#safe で尋ねてください。
• 拡充に協力を申し出たい？ #internal-handbook チャンネルに参加してください。

KPI

エンジニアリングチームとそのすべてのサブチームは、Handbook Update Frequency を KPI として追跡しており、目標はチームごとに異なります。現時点では、この KPI の有効性を分析・観察するため、エンジニアリングが Handbook update frequency を追跡している唯一のディビジョンです。

ハンドブックの外部利用

私たちが行うほぼすべてのものと同様、ハンドブックも オープンソース であり、他社が自社のドキュメントや慣行のインスピレーションとして使うことを想定しています。とはいえ、ハンドブックは常に 私たちが何をしているか に具体的であるべきで、私たちがどうありたいか ではなく、各企業は時間とともに自らのハンドブックを埋めていく必要があります。私たちのハンドブックは Attribution-ShareAlike 4.0 International license の下にあります。

GitLab にインスパイアされて

もし御社が GitLab のハンドブックに影響を受けたのなら、何に刺激を受けたのか教えていただけると嬉しいです。Inspired by GitLab ページ をご覧ください。

意義あるものにする

別の会社から、自社では機能していないハンドブックを私たちはどうやって機能させているのか、と尋ねられたことがあります。「何かがナレッジベースに文書化されているのに、読んだり検索したりしないので人々が知らない、というケースが多くあります。中には『壁のようなテキスト』と感じるものに対して強い拒否感を持つ人もいます。」

これについては、GitLab の ハンドブックファーストなドキュメントアプローチを受け入れるためのガイド でカバーしようとしています。

人々がハンドブックを見る時間を有意義なものにするために、上記の「ハンドブックのガイドライン」に従うだけでなく、以下のことも行いましょう。

1. ライティングスタイルガイド に従う。
2. 優れた検索機能を持ち、Google 検索 ができるよう公開する。
3. オンボーディング中に 知識 をテストする。
4. 実例を挙げる。
5. 企業用語を避け、友人に話すように物事を説明する。詳しくは、コミュニケーションガイドの シンプルな言葉 を参照してください。

Wiki 型ハンドブックはスケールしない

会社のハンドブックは wiki として始まることが多い です。 このフォーマットは、GitLab のマージリクエストと GitLab Pages を用いた静的ウェブサイトよりも、人々にとって作業しやすく感じられます。 しかし wiki は時間とともに陳腐化し、整理が悪く、古くなりがちです。

Wiki では、ページの複数箇所や複数ページにまたがる提案をすることができません。そのため、ハンドブックの再編成が難しくなります。GitLab のマージリクエストと GitLab Pages は分散バージョン管理に基づいているため、提出者と承認者の役割を分離できます。これにより、ハンドブックを最新に保つ作業の分担が可能になります。

• ハンドブックを読める人は誰でも提案できる
• リーダー (多忙になりがち) はそうした提案を承認するだけでよい

Wiki はまた、変更に関するコラボレーションも奨励しません。マージリクエストのように、提案された変更について議論する方法がないからです。

一部の wiki では、変更の差分を表示したりリンクしたりするのが難しく、意思決定を伝達するうえで必要な機能が欠けています。

Markdown ハンドブックの利点と wiki の限界についての Sid と Paul の議論

原文: https://handbook.gitlab.com/handbook/about/handbook-usage/ · 翻訳: 2026/4/19