より多く書き、より少なく話す：ドキュメンテーションとインナーソースで組織のレジリエンスを高める

原文リンク(2023-12-20)

思い浮かべてほしい。あなたは会社に入ったばかりで、社内の共有インフラプラットフォームについて学ぼうとしている。社内のドキュメントサイトを検索しても答えが見つからないので、Slackのような社内メッセージングツールに助けを求めようとしている。

Slackを通じて、別のエンジニアから質問の答えを見つけたが、その情報がどこにも書かれていないことに気づく。これは理想的な答えの見つけ方ではないが、よくあることだ。質問に対する回答は得られるが、次に同じ質問をする人はどうなるのだろうか？この問題は、ドキュメント化、ダイアグラム、アーキテクチャの決定、その他、システムがなぜそのように機能するのかを理解するための一般的な方法である。

ドキュメンテーションのやり方を改善することは、情報をより透明化し、アクセスしやすくすることで、組織のレジリエンスを構築するのに役立つ。QCon San Francisco 2023での私の講演では、優れたドキュメンテーションの課題といくつかの解決策について述べた。

文書化の不備は、さまざまな状況で組織のレジリエンスに影響を及ぼす可能性がある。

• 退職 - システムの仕組みを知っている人が一人しかいない場合、その人が退職すると継続性に支障をきたす可能性がある

• 入社時の課題 - 企業によっては、文書改善の負担が新入社員にのしかかることがある。「文書を見て、何が足りないか教えてください」というのは、あまり歓迎される導入ではない。

• 再編成 - 人の移動。チームは移動する。たいていの場合、前職でサポートしていたシステムはそのまま引き継がれる。新しいチームで新しいものを構築するはずなのに、サポートというお荷物を抱えてしまうのだ。

• 障害 - システムの仕組みを調べたり、正しいダッシュボードを見つけたりするために夜中に誰かを呼ばなければならない場合、障害が長引くことになる。また、夜中に誰かに電話しなければならないのは負担だ。もし彼らが休暇中だったら？

良い文書とは何か？

文章化だけでは、有用で発見しやすい情報という課題のすべてを解決できるとは限らない。読みづらい文書や冗長すぎる文書は、解決するよりも多くの問題を引き起こす可能性がある。文章を書くときは、以下のことを確実にすること。

• 有用である
• 関連性がある
• 正しく最新である
• 発見しやすい

文章化の課題解決策

文章を改善し、同時にレジリエンスを高めるために、チームやエンジニアリング組織内でできる調整がいくつかある。

非同期のコミュニケーションをする

人に紹介する前に、自分の問題をじっくり考え、書き出そう。そうすることで、非同期のコミュニケーションがうまくいくようになる。

最近、キドリンの法則に出会った。

「問題を明確に書き出せれば、問題の半分は解決したようなものだ。」

プログラミングにおけるラバー・ダッキングのようなものだ。同僚と重要な話をするときにこのようなことが起こるのを私は見てきた。何か大きな技術的な決断をしたいのに、彼らはそれをどう解決したいのか、自分の考えがまとまっていないのだ。彼らは会議で大きな変更を提案するが、なぜこの大きな変更をしたいのか、その理由がわかっていない。もしかしたら、問題を解決するためにこの特定のツールを使うというブログ記事を読んだだけかもしれない。ミーティングの参加者は、その変更を行なわない理由を特定し、エンジニアは落胆してその変更から手を引くことになるだろう。

私は人々に、1日か2日かけて、問題点が何であり、解決策が何であるかを書き出し、それを人々と共有することを勧めている。他の人たちにそれを理解する時間を与え、非同期でコメントさせる。こうすることで、より賢明な、解決策を導き出せる。

文章を書く文化を教え、奨励する

Google社などでは、テクニカルライティングのコースを用意している。これらは、あなたの組織がテクニカルライティングの基本を確実に身に着けるために非常に役立つ。これには、能動態で書くこと、正しい文法を使うこと、情報量は多いが冗長になりすぎないことなどが含まれる。私は以前勤めていた会社で、他の同僚と一緒にGoogle社のライティングコースを受講した。この過程により、チームとしての書き方を改善し、有用なドキュメントの量を増やすのに役立った。

文章を発見しやすくする

15年ほど前、私の職場にはGoogle Search Applianceがあった。これはGoogles社から購入し、データセンターに設置するハードウェア・アプライアンスだった。このアプライアンスは、社内のすべての文章をGoogle社の検索エンジンにできた。残念なことに、その製品は販売されなくなった。企業内の情報の検索性という問題は、いまだに大きな問題である。[画像ソース：Barabas,CC BY-SA 3.0, via Wikimedia Commons]

Google Search Applianceはもはや利用できないが、現在のところ、次のような代替手段がある。

• Backstageは オープンソースの開発者ポータルで、もともとはSpotifyによって書かれ、現在はCNCFのプロジェクトとなっている。すべてのMkDocサイトをBackstageにバンドルし、Backstageポータル内で検索できる。

• Google Cloud Searchは、Googleのツール製品を使用している場合に便利だ。MkDocサイトの一部を検索可能にするプラグインもある。

• Hermes はHashiCorpによるプロジェクトで、Google Docsの上に優れたインターフェイスを提供し、より検索しやすくしてくれる。

• Github のコード検索は、すべてのドキュメントをREADMEに保存しているなら、かなり良くなっている。

• Elastic Workplace Searchには、検索可能な外部ソースを追加するプラグインがある。

ほとんどの企業は、いくつかの解決策を組み合わせて使っている。これらのツールはどれも完璧ではないが、社内の情報の検索しやすく向上させることは、本当に価値のあることだ。

もう一つの話題は、図表の検索のしやすさである。これは、最高のツールを使っても難しい場合がある。私は最近、コードベースを記述する際に使用するC4ダイアグラム・スタイルを4つの詳細レベルを特定する際に使用するように、人々に勧めている。詳細レベルを区別することは役に立つが、すべてを1つの場所に置かない限り、ダイアグラムの発見性には必ずしも役立たない。もっとも簡単な場所は、ツールも存在するリポジトリだろう。共通の命名規則やフォーマットを使うことも、発見しやすくする助けになるだろう。

画像ソース

適切な動機付けを行う

私たちは、文章を書く際の動機をあまり持っていない。コードをプッシュしたり、ユーザーを助けたりすることは成功とみなされる。人々が同じ質問をし続けなくてもいいように文章を書くことは、成功とはみなされない。私たちのゴールは、ユーザーがプラットフォームのパワーユーザーになるために必要なだけの情報を提供することだと思う。情報を消化しやすくし、彼らが学習するのに精選する。

私は、『Badass:Making Users Awesome』（Kathy Sierra著）に基づくSmurti Patel氏の講演の例えが気に入った。人々を素晴らしい存在にするためには、ツールではなくユーザーに焦点を当てる必要がある。より良いカメラを作ることではなく、より良い写真家を作ることに集中するのだ。どのようなシステムであれ、ユーザーが質問する必要がないほど使いやすいものでなければならない。私たちは複雑なものを作っており、それはしばしばもっとも簡単な道ではない。

人々がどのように働くかを理解する

次に、リモートで働く人たちとのつながりや信頼関係を築くことに意図的に取り組む必要がある。以前勤めていた会社では、マネージャーがチームの規範やストーリーについて考えさせた。人々は、仕事での最高の日や最悪の日がどのようなものかを話し合った。ある人は、チケットシステムに入って、チケットの中に必要な詳細がすべて書いてあるチケットを取るのが好きだった。また、もっと曖昧な要件を求める人もいた。

マネージャーとして重要なのは、自分の期待通りに動いてくれないとイライラするのではなく、人々がどのように仕事に取り組むのが好きなのかを理解することだ。オープンで正直であること、共感を実践すること、そして人々がどのように働くのが好きかを話し合うことは、成功し生産的なチームを持つために重要である。

創造するための時間とスペースを提供する

情報を読んだり見直したりする専用の時間、さらには書く専用の時間を確保する。文書を読んでコメントすることを主目的とするミーティングを開いてみよう。これは少し直感に反するように聞こえるが、実に役に立つ。ミーティングでは、カメラやマイクはオフにする。文書を読み、コメントを加える。オンライン・ミーティングに参加することで、必要であればすぐにミュートを解除して質問できる。そうでなければ、前後に話をするのではなく、文書を読んで理解するための集中した時間を持つことができる。

そのような時間と空間を作るには、自分、チーム、組織にとって何が最適かを理解することが重要だ。金曜日をノーミーティングデーとして、より集中した仕事ができるようにしている企業もあるが、金曜日が必ずしもベストな時間とは限らない。Slackのような常につながっているツールは、集中力を削いでしまうので、あなたやあなたのチームは、集中できるようにすべての通知を無効にする時間を設定するといいだろう。気が散らないように、自分に合ったシステムを見つけよう。

アプローチに合意する

ドキュメンテーションの改善に取り掛かる際、形式的なパターンや図解ツールにこだわりすぎないこと。明確でシンプルな文書と設計があなたの目標であるべきだ。適切なツールやフォーマットが何なのかを考えすぎるあまり、多くの時間を費やすことになりかねない。作業するのに最適なコンピューターや、使うのに最適なエディターを見つけるのに何週間も費やした人の話を思い出す。とにかく始めてみて、そこから調整していけばいい。

すでに有用性が証明されているベースから始めるなら、RFC（意見募集）やADR（アーキテクチャ決定レコード）がいい。ADRのテンプレート例は以下にある。

アプローチを決める際には、いくつかの基本的なステップがある。

• アプローチの選択肢をブレインストーミングする
• ホワイトボードに書き出す。
• 提案を説明する文書を作成する
• トレードオフ（コストとベネフィット）をさまざまなグループで検討する
• エンジニアに回覧する-完璧になる前でも、ドキュメントを共有することを恐れてはいけない

より正式なオプションとして、アーキテクチャー・レビュー・ボード（Architecture Review Board）を利用できる。これは、全社的なエンジニアの持ち回りのグループで、毎年メンバーを変える。RFCやADRが書かれるたびに、チームはそれらをこのレビューボードに送り、全社を代表するエンジニアとしてフィードバックを与える。しかし、これは義務ではない。

しかし、決定が下される前に情報を拡散し、他の人たちからフィードバックを得ることは有用だ。普段は目にすることのないものをキャッチできることもあるし、自分が何も知らないような社内の別の部分からフィードバックが得られるかもしれない。特に私のようなプラットフォーム・スペースでは、他のグループに影響を与えることに注意を払っていない場合に備えて、それは貴重なものだ。

インナーソース（社内オープンソース）

インナーソースとは、オープンソースのベストプラクティスを利用し、組織内にオープンソース文化を確立するというコンセプトだ。プロプライエタリなソフトウェアを開発可能だが、社内の開発者やチーム間で仕事をオープンにしていくのだ。インナーソースの重要なアイデアは、サイロを打破し、透明性の高い文化でイノベーションを加速させることができるということだ。

企業文化や価値観、組織内部の制約を尊重しながら、より社内的なシェアリングエコノミーに転換する必要がある。チーム全体でオープンで透明性を高めることだ。

簡単な第一歩は、単一のバージョン管理システムを使用し、すべてのリポジトリへの読み取りアクセスを許可することだ。エンジニアから内部コードを隠す理由はないはずだ。

インナーソースは、チーム間での貢献を奨励することで、開発を加速させることができる。貢献者が増えるということは、共有ライブラリやツールにより多くのアイデアや改良が加えられることを意味する。このように参加者が増えることで、ドキュメンテーションが強化され、オンボーディングが容易になる。インナーソースはまた、重複したプロジェクトではなく、チーム間でのコードの再利用を促進する。一元化された共有コードは、凝縮された知識とコラボレーションの向上も意味する。

この構造により、レジリエンスが高まる。貢献者の幅が広がることで、プロジェクトは入れ替わりや再編成に耐えられる。組織全体でより多くのエンジニアが様々なシステムを理解していれば、移行もスムーズになる。また、より強固な文書化システムにより、新入社員のオンボーディングカーブも短縮される。オープンな文化は、勢いを持続させる継続的な貢献を引き寄せる。

結論

ドキュメントの発見可能性と情報の透明性は、レジリエンスの構築を目指す組織にとって重要である。強力なドキュメンテーションの実践と、知識共有を促進するための文化的規範の転換は、不可欠な作業である。より良い非同期コミュニケーション、文書作成に沿ったインセンティブ、構造化されたフォーマットなど、いくつかの戦術的な解決策は、チームをレジリエンスに向かわせられる。また、インナーソースのプラクティスも有効であり、企業は自社に適したものを採用できる。