Published on

GitLab Handbookに学ぶ

Authors
  • avatar
    Name
    Kikusan
    Twitter

GitLab Handbookから学べることを抜粋。

refs

ドキュメントを組織に導入する必要性

SSoT

Single Source or Truth：信頼できる唯一の情報源 は、スタック情報を1箇所で最新に保つことで、時間の浪費を避けられる。

ライブドキュメント

MTGではアジェンダとミーティングノートを必ず用意することで、非同期コミュニケーションが可能となる。
ミーティングノートにはライブドキュメント（参加者全員がミーティングしながら記載する）を採用すると、
あらかじめ質問を記載しておくこともできるし、発言のハードルも下がる。

いきなり鋭い質問をぶつけて相手を困惑させることを競う必要はない

プロセス・ロス

人がチームになった時にパフォーマンスの非効率が生じることを言う。
認識のズレや、無意識にペースを落とす社会的手抜きも含まれる。
ドキュメントを作成することで、バイアスが軽減され、プロセス・ロスを軽減できる。

認識の食い違い、3つの理由

  • 私たちは認識の階層を持っており、それぞれの階層レベルで正しいと感じる規範が違う
  • 遺伝子による感じ方の違いが存在しており、同じ刺激に対しても感じ方が違うという前提に気が付きにくい
  • バイアス：先入観、思い込み。正常性バイアス、知識の呪い、ハロー効果、感情ヒューリスティックバイアスなど

自分の正しさを押し付けるようなマネージャーは、GitLabやグローバルの企業では「マネジメントスキルが欠如しているマネージャー」とみなされる

ドキュメントはアウフヘーベンを促す

アウフヘーベン：意見と反論があった場合にどちらの意見にも価値があると認めて、総合的により高い段階に引き上げること

ドキュメントを作成して「共通の目的」を書き出すことで、「共有された現実」を作り出せる様になる。

ドキュメント・テキスト活用に関する思想とルール

ドキュメントに書かれていることを組織の公式見解として遵守する。そうでないとドキュメントを育てていくことは困難。

Tips

Valueを基準にする

公式ルールを定めることで、議論になった場合の基準として活用する。

https://handbook.gitlab.com/handbook/values/

ガイドラインを設定する

ドキュメント作成スキル

  1. 目的を設定する：ドキュメントの冒頭には読者が読んだ際に何を得られるのかを明記する。（読者は活用シーンを理解でき、作成者はドキュメントに記載すべき情報の取捨洗濯がしやすくなる。）
  2. 対象となる読者の範囲を記載する：目的の次に読者の範囲を記載する。前提となる知識はリンクを貼る。
  3. ファクトとオピニオンを分ける：情報の正確性・客観性を高めるため。
  • ファクトには出典を記載する。
  • オピニオンには**「だから何？」(So what?)**を記載する。自明だと思っていることは他の人には自明でない。
  1. １つの文は一つの論点に絞る：可読性を高めるため。
  2. 構造化を活用する：視認性を高めるため。
  3. 見出し、図表を活用する：視認性を高めるため。
  4. 具体的な言葉を使う：判断性を高める(解釈の幅を狭くする)ため。レバレッジ×、資金を借り入れて投資する⚪︎。
  5. 繰り返し使われる可能性が高い内容を1つのドキュメントにまとめる：再利用性、保守性を高めるため。
  6. ドキュメントの階層を整理する：再利用性を高めるため。
  7. 必要な情報に絞る：再利用性を高めるため。
  8. 適切なツールを使用する：保守性を高めるため。更新のハードルが低いとよい。gitlab、confluenceなど。
  9. テンプレートを活用する：保守性を高めるため。構造が統一化される。目次や索引がつくとなおよい。
  10. SDS法を活用する：Summary・Details・Summary法
  11. 書き手が期待している目的を達成しているか見極める：具体的な行動に言及しているかをチェック
  12. 第三者のつもりで読み直す：論理の飛躍がないかチェック
  13. より良い論理展開が存在しないか検討する：論理の展開をシンプルにする。目標意図と実行意図を考慮するのが効果的。
  • 目標意図：なぜ行動を起こす必要があるのか
  • 実行意図：どのように行動を起こすのか

テクニカルライティング

家電やソフトウェアのマニュアルを作成するためのものだが、多様な価値観や認識の差を乗り越えるのに有効。
誰が読んでも何をすればいいのかイメージしやすいドキュメントを作成できる。

基本的には伝わりやすい文章を作成するためのルールが記載されている。

Tips

  • パラレル構造：同じ構造の文を並べることで、情報を整理する。時制を揃える、能動態と受動態を混在させないなど。
  • トピックタイプ：項目のトピックの種類で、組み合わせてドキュメントを構成する。読者がパターンを認識しやすくなる。
    • Concept：機能や概念を説明する。
    • Task：手順を説明する。
    • Reference：表やリストで辞書の様に使う。
    • Trubleshooting：ドキュメントの最後に問題が発生した場合の解決方法や、補足情報を記載する。

GitLab Valuesのライティングに関係する行動原則

  • 感謝を伝える：関係性が悪化するとパフォーマンスは下がる。大袈裟なくらいに。
  • 思いやりを持つ：追い詰めるような文章を避け、相手がメッセージを受け入れやすくする。
  • 情報をシェアする：多くの人の利益になるよう。自身がコンテクストを学ぶ機会になる。
  • 知らない知識がある前提で振る舞う：気軽に誰かに質問して教えてもらうことが効率的。教えてもらったことはドキュメントにすることで感謝とする。
  • 活動ではなく影響を計測する：何をしたかではなく、何を達成したか。影響範囲を計測指標にする。
  • 全体最適を志向する：パートナー全体にとっての利益を最大化することで、最も重要なテーマを達成できる。
  • 退屈な解決策を選択する：慣れた解決策を選択することで、効率化できる。
  • 他人の時間を尊重する：事前にアジェンダを見てもらう、結論から伝える。
  • 最小限の変更を行い、最速でリリースする：最も効率的にするためには早く公開することが重要である。小さな変更を見せ早く周囲からフィードバックをもらう。
  • 可能な限り非同期を優先する：時間に縛られずに活躍できるようになる。
  • 多様な視点を求める：先入観による思い込みを発見する。
  • 何かを感じたら、声を上げる：フィードバックを送るため。
  • 全てが制作途中だと理解する：あらゆる成果物は変更される可能性があり続けるという前提をもつ。公開ハードルを下げ改善の可能性が見つかる。
  • プロポーザルを用意する：具体的なアクションを伴う提案を用意する。叩き台があることでリアクションしやすくなる。
  • まとめてしまいたくなる欲求に抵抗する：あれこれと取り組むことによるスコープクリープ（取り組みが増えるとCost/Deliveryが悪化する）を避けるため。

ドキュメントの保守

SSoTを維持するための保守のTips

  1. コミュニケーション手段は状況に応じて使い分ける。：SSoT↔️揮発性の高い情報 は手段によって変わる。ドキュメント＞イシュー＞チャット＞メール＞会議。アジリティは維持しつつ、SSoTに近づける。
  2. 品質責任者を決める：マージリクエストを受け入れる人を決める。
Discuss on Twitter