読書メモ。2025年22冊目。
『GitLabに学ぶ パフォーマンスを最大化させるドキュメンテーション技術』を読んでの感想となります。（2025/3/15記載）
本の概要
本書は、世界でも有数のドキュメント作成ノウハウを持っているGitLabを参考にした「ドキュメント作成」や「テキストコミュニケーション」の入門書です。
同社は、世界65カ国に2,000名を超えるメンバーが所属しているグローバルカンパニーです。
世界中のあらゆる場所や価値観、タイムゾーンに存在するメンバーのパフォーマンスを引き出すためには、ドキュメントが鍵であると同社は述べています。
情報が蓄積されたドキュメントが存在することで、必要な情報にいつでも多くの人がアクセスでき、信頼性の高い情報をベースに業務が進められます。
本書では、このような効果的なドキュメントがどうすれば作成できるのか、GitLabのドキュメント作成ノウハウに基づいて解説します。
また、GitLabのドキュメント作成方法はかなり具体的なルールや手法が示されていますが、その背景にある理論や研究についても触れることで、表面的な理解だけでなく根本の思想についても学習し、応用できるように説明します。
引用：
動機
- 今まで作るためのドキュメントにしか意識が無かった。
- プロダクトの成長に追随するドキュメントの扱い方が分からずにいる。
- GitLabのドキュメントを学びたい！！
感想
GitLabのドキュメントについて体系的に学べる１冊でした。
自分がプロダクト開発にあたるドキュメントをあり方を知りたかったのに対してはもっと俯瞰した内容でした。
ただ、そのことでよりドキュメントに求められる目的であったり、意義を認識することができました。
今のチームでは、開発プロセスにおける個々人の作業を、どうやってチームとしての経験として消化できるだろうかと悩んでいる部分があったため、感覚や感情も含めてドキュメントにアウトプットする、という内容は大きなヒントになりました。
また、目的な記載やイテレーションなど当たり前とも思える部分も、改めて念頭に置きたいと思いました。
また、何より自分の捉え方を見直したいと思ったのは、ドキュメントは作成者のものではなく、チームのものであるということ。個人の認識で作ったドキュメントも相互理解を深めて共通認識のものにしていく過程で、個人のものからチームのものに転換していく。
そうすることで形骸化せず持続的にアップデートできるものになるイメージができました。
具体的な設計ドキュメントについても、今回の書籍を念頭に策定していきます。
忘れたくないメモ
■ドキュメントの意義
あらゆる人たちと協力して物事を進める上で、ドキュメントという客観的な場でお互いの情報をアウトブットして確認し合うことが効果的。
■プロセス・ロス
チームで個々人の何をなすべきかの認識がずれから発生するパフォーマンスの非効率をプロセス・ロスと呼ぶ。チームの方針が定まっていれば、認識のずれが発生することもなく、関係悪化という事態も生じない。
■認識のずれによる影響
過去の経験や物事の捉え方によって、個々人の認識の枠組みは異なっているため、何を達成するべきなのかという目的や優先順位が一致していないと食い違いが発生する。
■チームの認識の揃え方
チームになることで発生する認識のずれも存在し、無意識のうちに自分一人のときよりもペースを落としてしまう「社会的手抜き(social loafing)」や「調整の損失(coordination loss)」と呼ばれる現象もプロセス・ロスの一種。互いの認識をドキュメント上で明確にすることで、認識のずれをそろえるための議論ができるようになり、コストパフォーマンス良く客観的な視点で物事を処理できるようになる。
■定性的な内容も含め共通認識を作る
感覚や感情も含めてドキュメントにアウトプットすることで、認識の違いを乗り越えるヒントになる。異なる人間の間でそれぞれが感じている現実を説明し、理解し合うことで共通認識を作り上げる。共有された現実を「意識的に作る」ことが、チームでコラボレーションする上で重要。ドキュメントを活用する際には、「共有された現実」を作り上げていくことが目的であることをチームの共通認識として持つ。
■教養
「教養」とは単に物事の知識が豊富であることではなく、相手との対話の中で「互いにより良いものを目指してい姿勢」（ヘーゲル）。ドキュメントの考え方も、ソフトウェアがより効果的に機能するように改善し続けるという意味では教養的な存在。
■認識の土台を構築する
多様な存在である私たち一人ひとりが持つ異なった認識を、ドキュメントを活用し共通の目的にし、客観的に見ることで認識の食い違いを乗り越え、あらゆる人にとってより良い認識の土台を構築することを目指す。
■すべてのドキュメントはより改善できる下書き
GitLabのValueのひとつ「Results for Customers(顧客のための成果)」の中に、「活動ではなく影響を計測する」という行動指針がある。顧客やチームメンバーに影響を与えなければ成果とはいえない。まずは、他の人の目につく場所に公開し、顧客やチームメンバーに影響を与えることが重要。こうした考え方から、すべてのドキュメントはより改善できる下書きであるというスタンスを取ることができる。
■目的の明示
ドキュメントが達成したい目的を記載することで、ドキュメントに記載すべき情報の取捨選択がしやすくなり、目的が達成できる内容になっているかのチェックもできる。ドキュメントを公開した後、読者の反応を見ることで目的が達成できているのか振り返りができる状態になる。読者が目的が達成されないと感じた場合、作成者に追加の情報を求めたり、読者が情報を追加したりすることで、より多くの人に価値あるドキュメントに改善していくことができる。
■ディビッド・ゴルフ「経験学習モデル」
具体的経験 (Concrete Experience)
→内省的省察 (Reflective Observation)
→積極的実践 (Active Experimentation)
→抽象的概念化 (Abstract Conceptualization)
■イテレーション
最小限の変更で素早くリリースして、ユーザーのフィードバックを受けながら、改善を積み重ねる。
■オピニオンの記載
ファクトではなく、ファクトに基づいたオピニオンとして「だから何? (So what?)」を伝えるようにする。
■目標意図と実行意図
行動変容を促すために、「目標意図」と「実行意図」を考慮する。
目標意図とは、「なぜ行動を起こす必要があるのか」という目的が伝わっているかという観点。メリットや解決すべき課題を明確にすることで示す。ドキュメントを読んだ人がやる意味があると思えるか。
実行意図とは、「具体的にどうやったらいいのか」という目的が伝わっているのかという観点。やる意義が伝わったとしても、やり方がわからないと行動にはつながりづらい。どのようにやれば達成できるのかという具体的な方法を明示する。
■意図をしっかり伝える
ドキュメント作成者と読者の間での解釈の違いや曖昧な部分を、詳細な言語化を行い解釈性の低いドキュメントに改善していくことを繰り返す。これによりドキュメント作成者が意図しているメッセージが、誤解なく相手に「伝わる」ことを追求できる。ドキュメントやメッセージの意図をしっかりと伝えるためには、情報にアクセスしやすいことと解釈の余地が少ないことが重要となる。
