はじめに
こんにちは。ZENKIGENデータサイエンスチーム所属のredteaです。原籍はオムロンソーシアルソリューションズ株式会社 技術創造センタですが、社外出向でZENKIGENに所属しており、数理最適化や機械学習を用いたデータの分析業務、それらの結果に基づいた顧客への提案をしております[1]。所属チームでXを運用しており、AIに関する情報を発信していますのでご興味あれば覗いてみてください。
本記事は読書感想文でもなければ、自分用の読書メモでもありません。本書を全ビジネスパーソンへ強く勧めるために書いた、推薦書です。まずは何故この本を紹介するかご説明します。
なお、以後『GitLabに学ぶパフォーマンスを最大化させるドキュメンテーション技術』のことを「ドキュメンテーション技術本」や、「この本」と呼ぶこととします。
推薦する理由
結論から申し上げると、実践可能性と有用性が非常に高いからです。
約1年前の2023年09月11日、この本の兄貴的な存在である『GitLabに学ぶ 世界最先端のリモート組織のつくりかた ドキュメントの活用でオフィスなしでも最大の成果を出すグローバル企業のしくみ』が発売されました。この本はXなどで話題になり、私も購入して読みました。
『リモート組織のつくりかた』を読み終えた後、すぐに会社の同僚や上司に勧めて回ったくらい[2]、この本から学ぶことは多かったです。しかし一方で、個人レベルではどうにもならないことがたくさんあることにも気づきました[3]。
それから約1年が過ぎた先日、以下の投稿でこの本の存在を知りました[4]。
今度は「ドキュメンテーション技術」か...。
『リモート組織のつくりかた』にもドキュメンテーションに関する説明は結構ありましたが、それに特化した形です。ドキュメント作りなら個人で作るものや、チーム内でレビューするものから始められることが多いのではないか？ と思い読み進めましたが、この予測は的中でした。さらに、この本は職種を選びません。
テキストによって物事を伝えること全般を扱っているので、
- エンジニア
- 営業
- 広報
- デザイナー
- スタッフ
- マネージャー
全てのビジネスパーソンが持っていると周囲が喜ぶマインドセット、テクニックが満載です。この種のテクニックを習得することはある意味思い遣りと思っています。相手が理解しやすいよう、相手の手間を省けるようにと考えると、自ずとドキュメンテーション技術にたどり着きます。この種の思い遣りは、組織内で伝搬していくと信じています。「あの人のドキュメンテーションがとても分かりやすかった」、「あの人のメッセージはいつもわかりやすい」が、今度は「あの人のドキュメンテーションスタイルを真似てみよう」へと変わっていきます[5]。そうなれば組織内は素敵なドキュメントで溢れてきます。そんな状況を目指して、私はこの本を推薦します。
総評
この本のタイトルの『ドキュメンテーション技術』の部分はある種の誤解があるのではないかと思います。少なくとも私は、『ドキュメンテーション技術』という言葉は、ソフトウェア仕様書や手順書の類を指しているものと思っていました。しかし、この本が扱うドキュメントとは、ソフトウェア仕様書などに限ったものではありません。この本は、チームメンバーとのチャット、会議のアジェンダ、イシュー[6]など、業務上キーボードでタイプするほぼ全てのテキストを指しています。
一般的に想起されるドキュメントに閉じない、チャットなどのテキストコミュニケーションや通話/対面などの同期コミュニケーションでも応用の効く技術が、理論的な背景まで含めて解説されています。
これらの技術は、細かなテクニック、考え方、フレームワークや思想など、さまざまな粒度で解説されていますので、今日その日から役に立つテクニックから、5年後10年後の血肉となるようなマインドセットまで含まれます。自身のドキュメンテーション技術の向上はもとより、「ドキュメンテーション技術本」の普及で素晴らしいドキュメントで溢れれば自分が仕事しやすくなるので、この本を強くお勧めしたいと思っています。これが本記事執筆の一番の目的です。
本記事の構成
構成を先に示さねばならぬほどのボリュームはありませんが、アウトラインを示すことは重要です。「ドキュメンテーション技術本」は序章+3部の構成です。本の「部」と、本記事の「章」を1対1に対応させて記事を書きました。
第1部では、GitLab社のドキュメントに関する総論です。何を対象に、どんな状態を目指しているのかを具体的に示しています。また、学術的な知見を引用しながら、何故（悪い方向として）そうなってしまうのか、何故そう改善するとうまくいくのか、を丁寧に解説してくれています。本記事をどこかで見かけて覗きにきてくださったあなたは既にドキュメンテーションに課題を感じていらっしゃるかもしれませんが、おそらくそれ以上に、ドキュメンテーションの奥深さを感じることになると思います。本記事では「ドキュメントを理解する」という章で、序章と第1部の内容をごく一部のみ抜粋して紹介します。
第2部では、ドキュメンテーション技術について書かれています。ドキュメンテーションにおけるマインドセット、ドキュメントの具体的な書き方、と様々な粒度での説明があります。対象は広範に渡りますが、本記事では「ドキュメンテーション技術」という章を設け、技術資料とコミュニケーションの2つの切り口で紹介します。これは私の実務上実践している内容で、共感度が高いものを紹介するためです。
第3部では、個別シーンでのより具体的なドキュメンテーション技術について書かれています。それぞれのシーン別の具体的なテンプレートも載っており、それを手元に置くためだけでもこの本を購入する価値があります。本記事では「シーン別ドキュメンテーションパターン」という章で概説します。
ドキュメントを理解する
テキストベースでやりとりするよりも、直接話したほうが早いと思ったことはありませんか？ チャットやメールのやりとりに限らず、ある手順を伝える際に、ドキュメントを作って渡すよりも、通話したり直接会って話した方がスムーズに伝えられると考える人は多いのではないでしょうか[7]。
何故ドキュメント作成のコストは高いと思われるかというと、言語化と文章構成が面倒だと感じるからだと本で説明されています。しかし、これについては「ドキュメンテーション技術本」では以下のように断言されています。
文章の組み立て方をパターン化することができれば、決まったパターン通りに文章を組み立てればいいわけですから、文章構成を検討する労力をなくすことができます。また、伝えるべき内容を頭の中でどう整理すればいいのかフレームワークを学習すれば、抑えるべきポイントが漏れなく整理でき、伝わりやすいドキュメントを作成できるはずです。
このように、やり方を知らないだけ、慣れていないだけで、避けていたドキュメンテーションは、学習によって身につけられるのです。
ドキュメンテーションの対象
総評でも書いた通り、「ドキュメンテーション技術本」で扱うドキュメントはかなり広範です。
- アジェンダ
- ミーティングノート（議事録）
- イシュー
- 報告書
- チャット
- メール
- ・・・
とにかくテキストをキーボードでタイピングするもの全てといっても過言ではありません。本記事では、チャットやメールなどのコミュニケーションに関するものとそれ以外で節を分けて紹介するようにします。
箇条書きで書いたものの大半は、なんとなくイメージがつくと思いますが、「イシュー」だけはピンとこない方もいらっしゃるかと思いますので、ここで解説します。イシューはエンジニアの方はGitHubなどで馴染みある単語かもしれませんが、その概念をそのまま業務全体に拡張したようなものです。「ドキュメンテーション技術本」では以下のように説明されています。
イシューとは、業務で取り組んでいるプロジェクトやタスクを管理するものです。たとえば、「商談データから受注率の高い顧客の特徴を発見する」「採用サイトを更新する」「新機能に関するマニュアルを作成する」といった内容でイシューを作成します。イシューはタスクだけではなく、他の人と協力して進めるプロジェクトや特定のテーマに対する質問をするだけのものもあります。
イシューには、工数の見積もりや実際に費やした時間や進捗状況も記載します。これによって、誰がどんな業務に取り組んでいるのか一目で分かります。私の現在の所属組織では、Notionのボードビューにてイシューを管理しています。自身のタスク管理だけでなく、チームメンバーの状況も把握できて大変便利です。
ドキュメント運用の真髄
コミュニケーションに関するもの以外の、ドキュメント運用の真髄は以下の2つに集約できます。
- ドキュメントは信頼できる唯一の情報源である
- 全てのドキュメントは下書きである
ドキュメントは信頼できる唯一の情報源である
GitLab社には、「The GitLab Handbook」という、ドキュメント運用の真髄といえるものがあります。これはGitLab社がまだ10名程度だった頃から社外に公開されている、GitLab社のあらゆることが集約されている情報源です。現在3,000ページにも及ぶ巨大なドキュメントですが、ここに書かれていることと実態が乖離したり、矛盾する情報が存在しないよう、GitLab社では公式情報はハンドブックのみに集約するというルールを定めています。この手法は、情報システム設計の用語で、信頼できる唯一の情報源（SSoT: Single Source of Truth）と言われています。
-
アクセス性
社内の知識はドキュメント化されていなければなりません。求めている情報が誰かのローカル環境や頭の中にしかない場合は、その人へ直接聞きに行かねば情報が得られません。 -
透明性
ドキュメントが外部メンバーに公開されていない場合、他の人の視点が入らないので、暗黙知が入り込みやすくなります。新メンバーなど、事前の背景などがない人が見たときにわかりやすい状態を維持するためにも、チーム外にドキュメントは公開すべきです。もちろん、個人情報などが含まれるもの等例外はたくさんあると思います。 -
信頼性
情報が複数の場所に存在し、それらが矛盾していると、ドキュメントの情報は信頼できませんよね。また、口頭での説明に頼っていると、説明する人によって内容が変わってしまう恐れがあります。関連する情報をリンクするなどして、一元的に、最新の状態を維持することでドキュメントの信頼性は向上します。
これらの運用方針は「The GitLab Handbook」にかぎった話ではなく、技術資料やミーティングノートなどの全てのドキュメントに共通することと思います。これを実践し続けることは想像以上に難しいと思いますが、そのためのヒントはこの本にたくさん書かれています。
全てのドキュメントは下書きである
GitLabには「全て下書きである」という行動原則があります。
「ドキュメンテーション技術本」より引用した通り、GitLab社はドキュメントとは動的なものと考えています。一般的な企業では、ドキュメントを作成する際には「完璧なドキュメント」を作ろうとしているのではないでしょうか。ドキュメントのレベルによっては、3つ以上のハンコ[8]が押されることによって完成する場合があります。もっと悪いことには、ドキュメントの更新にも3つ以上のハンコが必要だという話も聞いたことがあります。
ドキュメントの品質を担保するためには上長による確認は1つの有効な方法ですので、これを否定する意図はないのですが、ここに根本的な考え方の違いがあります。GitLab社の考え方は次のとおりです（「ドキュメンテーション技術本」より）。
まずは人の目に触れる状態にして、可能な限り早くフィードバックが得られるようにすることを重要視しているのです。
GitLab社には"Results for Customers"という「自分たちがどれだけ活動したか」よりも、「顧客やチームにどれだけ影響を与えられたか」を重要視する文化があります。どれだけ時間をかけてドキュメントを作っても、それが公開されなければなんの影響も発生しません。従って、まずは人目のつくところで公開することがなによりも重要なのです[9]。
また、過去正しかったものが今正しいとは限りません。動的に、常に最適な状態を目指し続けるというスタンスが、ドキュメントは下書きであるという表現に表れていると感じます。
ドキュメンテーション技術
技術資料などの一般のドキュメントと、チャットなどのコミュニケーションにまつわるものと、分けて紹介します。
技術資料などの一般ドキュメントのテクニック
「ドキュメンテーション技術本」で紹介されている内容のうち、私自身が特に重要だと思って意識している事柄をいくつか紹介します。
目的を設定する
効果的なドキュメントを効率的に書くには、冒頭にそのドキュメントの目的を明記することが重要です。目的を明確にすることで、情報の取捨選択が容易になります。そして、ドキュメント推敲時には目的に沿っているかをチェックすれば良いので、第三者にとってわかりにくいところ、不足しているコンテキストがないかなどに気づきやすくなります。また、目的を設定することは想定読者を設定することも含まれます。
目的の例としては、「ドキュメンテーション技術本」では以下が挙げられていました。
「施策の振り返りを行い、次に取るべき方向を明らかにする」、「経費精算を却下されることなく承認されるようにする」
ちなみに本記事の目的は、「ドキュメンテーション技術本」を1人でも多くの方に読んでいただくことです。想定読者はまずはこの本をまだ読んでいない私の周囲の人々ですが、ついでにZennで公開することで、同じ志を持つ仲間が増えれば嬉しい限りです。
コンテキストを書く
ドキュメントは完成するものではないということを、全てのドキュメントは下書きだという表現で説明しました。完成されたドキュメントですと、ついつい簡潔に結論だけを書いてしまいたくなるかもしれません。そうではなくて、何故現在、その決断に至ったのか、何故その仕様にしたのかのコンテキストを明記することが重要です。
チェスタトンのフェンスという言葉があります。Wikipediaによると以下のように説明されています。
チェスタトンのフェンスとは、なぜその仕組みがあるのかがわからないうちは、その仕組みを変えるべきではない、という考え方であり警句である。
ドキュメントは動的に変わるものなのですから、変更するときには、その変更する箇所がどのような経緯で書かれたのかを知る必要があります。また、コンテキストを明確にすることで新たにチームに加わる人もスムーズにオンボードできます。コンテキストこそが社内の知見なのです。
正確性・客観性
ドキュメントに書かれていることに誤りや、作成者の独断で客観性に欠ける内容だと困りますよね。いくらドキュメントは下書きだとは言っても、ドキュメントの品質を維持するための工夫は大前提です。
-
事実と意見を分ける
プレゼンテーション資料作成術なんかではお馴染みですが、これが曖昧だと意思決定を誤ってしまう恐れがあります。事実を述べる際には、可能な限り情報源やデータを添えたり、リンクから確認できるようにしましょう。
本記事では、基本的に「ドキュメンテーション技術本」に依る事実ベースで書き、特にそのまま引用する際は引用フォーマットを用い、自分の意見では「〜思います。」などと表記するようにしています。徹底するのであれば、事実と意見を完全に分ける雛形を作ってしまってもよいかもしれません。 -
可読性・視認性・判断性
ドキュメントの内容が正しくとも、読みにくければ読んでもらえません。一文一意、一文の長さ、フォント、色、など、基本的には具体的、定量的に設定できます。
こちらの書籍『GitHub CI/CD実践ガイド』を読みやすくする技術という記事もお勧めなので是非見てください。 -
再利用性・保守性を意識する
プログラマなら同じ関数定義を何度もやりませんよね。用語の定義も繰り返してはいけません。再利用性、保守性を高めるためにはページ内リンクを上手に活用しましょう。それだけでメンテナンス性や一貫性が向上します。
2024年現在のほとんどのドキュメンテーションツールならページ内リンクくらいは使えるはずです。「会社にXXなんていう使いにくいツールの使用を強いられている」なんて愚痴をこぼさずに、ツールの使い方にも習熟しましょう[10]。
その他テクニック
ちょっとしたテクニックも紹介します。
パラレル構造
パラレル構造とは、複数の要素がある文を書く際には文法を揃えることです。読者は理解しやすくなり、可読性が向上します。以下、「ドキュメンテーション技術本」での例を紹介します。
- パラレル構造ではないの文の例
素晴らしい学生とは、テストで良い点数をとったことがあり、周りのクラスメートから信頼され、勤勉な生徒です。
- パラレル構造の文の例
素晴らしい学生とは、博識かつ誠実で、勤勉な生徒です。
トピックタイプ
トピックタイプとは、各項目の話題を限定することです。基本的にドキュメントはトピックタイプを組み合わせて作っていきます。例えば以下の項目があります。
- コンセプト
- タスク
- リファレンス
- トラブルシューティング
トピックタイプを意識して書くことで、書く内容がハッキリし、ドキュメントが読みやすくなります。また、トピックタイプごとの雛形を用意すれば効率化、品質の底上げも期待できます。詳しくは「ドキュメンテーション技術本」を手に取ってご確認ください。
コミュニケーションのテクニック
2024年12月現在、リモートワークから出社への回帰の流れは幾分かありますが、出社していてもテキストでのコミュニケーションは取りますよね。面識のないメンバーは当然ながら、信頼関係が構築できているメンバー同士であっても、相手へのリスペクトは忘れてはなりません。これはビジネスに限らず、プライベートでも使えるテクニックです。
感謝を伝える
対面で何か教えてもらったり、何かもらったら感謝を伝えます。これがテキストになるとできない人がいるらしいです。ついつい自分向けの情報ではないと思ったときや、既に知っている情報であったりすると、リアクションが薄くなりがちです。薄い反応は発信した側のモチベーションの低下に直結してしまいますし、今後教えてもらえるかもしれない有用な情報が手に入らなくなる恐れもあります。「ドキュメンテーション技術本」には、自分の今の感情の1段階上の反応を示そうという表現で説明されていました。
当然、感謝の気持ちは伝えなければ伝わりません。そして、沈黙は無メッセージではなく、攻撃的なメッセージです。沈黙を受け取った側の気持ちを考えれば、これ以上の説明は不要ですよね。
忘れてしまいがちな事実かもしれませんが、感謝を伝えられていないことに自覚がある方は、職場に限らず周囲の方へ感謝を伝えてみましょう。それだけで人生が少し変わることもあると思っています。
絵文字を使う
正直私は絵文字を使うのが苦手で、あまり実践できていません。意識的に末尾に「！」をつけている程度です。テキストだとどうしてもそっけなく感じてしまいます。何かを実施するかどうか確認の連絡を入れたときに、以下の反応でしたらどちらの方がやる気がでますか？
それでお願いします。
それでお願いします！
私は後者の方が断然やる気が出ます。私は単純な人間なのかもしれません。
意図を伝える
「XXは難しいです」と書かれていたらどのように受け取りますか？ もちろん前後のコンテキスト次第ですが、「難しいからやめておきましょう」というメッセージに受け取る人もいれば、「よっしゃ難しいからこそ頑張ろう！やるぜ！」と受け取る熱いメンバーもいるかもしれません。曖昧な表現で終わらずに、意図を明確に伝えるようにしましょう。
だいぶ昔に実際に観測した実話を少し改変して紹介します。勤務地の異なる社員がオフィスに来て、会議室A001でMTGに参加する予定でした。その社員は会議室の場所がわからず、MTGに遅刻しそうだったので、
会議室の場所がわからずに迷っています。
とだけ送りました。これでは受け取った側は待てば良いのか、それとも何か情報を伝えれば良いのかわかりません。受け取った側が親切で何か伝えようという気持ちがある人であっても、どんな情報を与えれば良いのか迷ってしまいます。
会議室の場所がわからずに迷っています。5F西側のエレベーターホール前にいるので、迎えに来ていただけないでしょうか。
具体的な意図を伝えることで、時間ロスや細かなストレスが軽減されます。会議が始まってしまって迎えに行くことが難しい場合でも、具体的なやり取りは建設的な方向に運びやすいです。
シーン別ドキュメンテーションパターン
第3部では個別シーンでのドキュメンテーションについて深掘りされています。全てのドキュメントを信頼できる唯一の情報源に仕立て上げると、かえって機動力が低下してしまいます。状況に応じて、適切な運用が必要で、そのノウハウやドキュメントのテンプレートが記載されています。以下、「ドキュメンテーション技術本」にて扱われている使用シーンです。
- ハンドブック
- アジェンダ
- レポート
- チャットコミュニケーション
- メール
- イシュー
詳しくは本を手に取ってくださいね。
ただしここで重要なことは、「ドキュメンテーション技術本」の内容を鵜呑みにしないことです。例えばメールを送る際、
アクションが必要なくても、常に「全員に返信」で返信する
と「ドキュメンテーション技術本」では紹介されています。こうすることで
- 相手が届いたことを確認できて安心できる
- 情報は常にみんなに見えるところで共有する
というようなことが達成できるそうです。一方、自分に関係のないメールが大量に届くと鬱陶しいと感じる人もいるでしょう。特に営業職の方なんかは50~100件ものメールが毎日届きます。こんな中で自分に関係のない案件のせいでメールボックスがいっぱいになっていては業務効率に影響が出そうです。コミュニケーションやドキュメンテーションのルールを作る際は、関係者達のおかれている状況に耳を傾けて、実態に合わせて制定せねばなりません。また、その時に何故そのルールを作ったのか、を含めてルール化することで、前提が変わった時[11]には柔軟にルールを変える意思決定ができます。
結び
私は創業100年近いメーカーと、創業10年未満のスタートアップの2企業に属しており、その文化の違いを体感しながら業務にあたっています。片方の組織では当たり前なことが、片方の組織では想像もできないようなことはたくさんあります。その良し悪しについて組織の状況、企業形態によって大きく変わるので一概に論じることはできません。事業形態、社員数等がこれだけ異なる企業間では、当然最適なルールも異なります。大事なことは、その時々で最適なルールは変わり、状況に応じて変化し続けなければならないということです。これだけは両企業で共通して言えることだと思います。
この「ドキュメンテーション技術本」には、読者の所属組織では当たり前にやっていることも書いてあるでしょうし、そうでないものもたくさんあると思います。ご自身の組織の状況と照らし合わせて、何をどう変えていくと良いか考えることはとても大切なことと思います。そのきっかけとして、グローバルリモート組織であるGitLab社の事例を知ることから始めるのはいかがでしょうか。この本1冊で他社の組織文化を感じることができるのは、圧倒的なコストパフォーマンスだと思います。
私はアフィリエイトなどとは全く関与していません。この本が売れても私には一銭も入りませんが、この世界のドキュメントが少しでも良くなれば、回り回って私の利益になると信じています。もちろん私自身も、少しでも周囲の方が働きやすくなるよう、ドキュメンテーション技術の向上に努めてまいります。是非、「ドキュメンテーション技術本」を手に取ってみてください。「リモート組織のつくりかた本」も「ドキュメンテーション技術本」くらいお勧めですので、2つの本へのリンクを貼ってこの記事を締めくくります。
参考文献
- 千田 和央. GitLabに学ぶ 世界最先端のリモート組織のつくりかた. 翔泳社, 2023.
- 千田 和央. GitLabに学ぶ パフォーマンスを最大化させるドキュメンテーション技術. 翔泳社, 2024.
お知らせ
少しでも弊社にご興味を持っていただけた方は、お気軽にご連絡頂けますと幸いです。まずはカジュアルにお話を、という形でも、副業を検討したいという形でも歓迎しています。
-
執筆当時 ↩︎
-
行動力のある仲間達は勧めたその場でAmazonでポチってくれていました。素晴らしい方々に囲まれていて私は幸せ者です。 ↩︎
-
もちろん、実践できることも大いにあり、非常に役立つ本であることに変わりはありません。それに、個人レベルでどうにもならないことだと完全に諦めているわけでもありません。できることは案外身近に落ちていたりするものです。 ↩︎
-
これを見た瞬間に発売日に届くよう予約し、通勤時間や歯磨きの時間を利用して一気に読みました。 ↩︎
-
個人の取り組みというよりも、ドキュメンテーションのルールを制定する方向に持っていくことのほうが重要ですが、いきなりそれを浸透させることは難しいですよね。そういう場合には、草の根から広めていくことは有用な方法だと思っています。 ↩︎
-
ドキュメンテーションの威力は、複数人に伝えるときや、来年入ってくる社員への情報伝達などの効率化の部分で発揮されることは言わずもがなです。しかし、一旦そのスケーラビリティを抜きにして考えてみましょう。 ↩︎
-
電子印を含みます。 ↩︎
-
本記事はチームメンバーだけに共有するメモのつもりで書き始めたものでしたが、「ドキュメンテーション技術本」に倣って、まずは人目のつくところ（Zenn）で公開してみました。 ↩︎
-
データ分析で尊敬する先輩が、私が使いにくいと思っていたソフトウェアを圧倒的に使いこなしているところを見た経験があります。新しいツールを導入するよう動くこともときには必要かもしれませんが、現状で最大のパフォーマンスを出す努力も忘れてはなりません。 ↩︎
-
例えばAIによって精度100%でその人に関係のないメールは自動アーカイブできるようになった等、現時点では想像しにくいような状況になるかもしれません。 ↩︎
Discussion