巻頭言：一人SREsのドキュメンテーション実践

著者：しょっさん
目次

今回の巻頭言は、一人でSRE活動をやっている中で実践しているドキュメンテーションに関するTipsと、最後に来年開催致しますSRE Kaigiの話を少しいたします。

SREにおけるドキュメンテーション

SRE活動を行う上で、ドキュメンテーションは非常に重要です。その重要性は「SREの探求」にも記載されているように、ドキュメントの有無や品質はサービスの信頼性にまで影響が及びます。
それほど重要なドキュメンテーションですが、一人でSRE活動を行っている場合、どのようにドキュメントを作成し、運用していけばいいのか？というのは非常に難しい問題です。

私自身も一人でSRE活動を行っている中で、ドキュメントの作成や運用について悩んでいました。そこで、実践しているいくつかのTipsを紹介します。

開発とドキュメントは必ずセットで進める

SREsとして開発を行うことは多々あると思いますが、必ず何かを作成したらセットでドキュメントを作成するようにしましょう。ドキュメント作成は知識の透明性を保ち、SREsと他のチームのサイロ化を防ぐための一つの手段です。
一人でSRE活動を行っていると、どうしても知識やコンテクストが自分の中で完結してしまいがちになります。それを防ぐためにも、必ず開発とドキュメントはセットで進めるようにしましょう。

後述するのですがコードに近いところにドキュメントを配置することが重要で、それと合わせてワークフローにドキュメント作成を必ず組み込むことをGitHub Actionsで強制する方法も出来そうだなと考えてはいるものの、実現できていないのが現状です。（*.mdが含まれていなければPull RequestのMergeを通さないなど）
こういった仕組み化が出来れば、仮にSREチームとして人数が増えた場合も、ドキュメントが存在しない！といったことが起こることが防げるでしょう。

ドキュメントはコードに近いところに配置する

ドキュメントはコードに近いところに配置することが重要です。これは 「SREの探求」の19章 にも、また 「Googleのソフトウェアエンジニアリング」の10章 にも書かれているのですが、ドキュメントの作成を行う際に考えるべきことは “コンテクストスイッチのコスト” です。
例えば、コードを書いている時に付随するドキュメントを変更しないといけない場面でいちいちブラウザを立ち上げてWikiを開いて、ドキュメントを探して、編集するといった作業は非常にコストがかかります。

このような無駄なコストを無くすためにも、コードの近くにドキュメントを配置し、なるたけコンテクストスイッチを減らすようにしましょう。私はIaCリポジトリなどで実践していますが、Terraformに慣れていない開発チームがドキュメントを読むことで理解の支えになるよう、何をどう管理しているのか？これはどういった理由から書かれているのか？どの公式ドキュメントを読めば、より理解できるか？などを手厚めに書いています。

また、このTipsのもう一つの利点として、GitHub Copilotにおける knowledge bases の活用にも繋がります。


knowledge basesはリポジトリ内にあるMarkdownを読み取ることで、Copilot Chatの精度を高めることができます。しかし、注意点としては一休さんの以下の記事にもある通り、 “日本語で書かれたドキュメントでどこまで精度を上げることができるのか？” という疑問はまだありますので、あくまでもCopilot Chatのサポートとして捉えるべきかと思います。

構造の複雑さに応じて品質を変える

「SREの探求」にも書かれていましたが、

Anne Lamottが 「くそみたいな第一稿」(shitty first draft) と表現する考え方を受け入れることが大切です。
つまり、 不完全なドキュメントは未だ存在しない完全版よりも圧倒的に有用 なのです。

とあるように、ドキュメントは存在するだけでも価値があります。また、ドキュメントにかけるコストは、かけようと思えば無限にかけることができます。SLOを100%に近付ければ近付けるほど、コストは指数関数的に増えていくと言われていますが、ドキュメントについても同様です。
そのため、ドキュメントに書かなければいけない事象の複雑さによって、どれだけの品質でドキュメントを書かなくてはいけないか？と品質のグラデーションを意識することが重要です。

例えば、GitHub Actionsのreusable workflowとして作成されたSlackに特定のメッセージを送るワークフローのドキュメントは、コードのコメントに書いておけば十分でしょう。逆に、Cloud workflowsからCloud Functionsを幾つも発火させて動作させるような複雑な構造の場合は、図解や細かめの説明を含めてドキュメントを作成する必要があるでしょう。

何を当たり前な、とおっしゃる方もいるかもしれませんが、 当たり前と思っていた前提知識が他チームのメンバーには当たり前ではないこともある ので、改めて意識することが重要です。時には、他チームのメンバーにドキュメントを読んでもらい、理解しづらい部分を指摘してもらうのもいいでしょう。
私の場合は、手厚めに書いたドキュメントは必ず書き終えた後に、他チームへ共有する場を設けて、その場で分かりづらいところはなかったか？などのフィードバックをもらうようにしています。ドキュメントにもレビューは必要なのです。

まとめ

そこまで大したことはやっていませんが、ドキュメンテーションの中で大切にしていることを挙げてみました。中々、SRE × ドキュメントの話は少ない気がするので、今後このような話が増えると良いですね。
あとは「SREの探求」のドキュメントの章の副読本として、「Googleのソフトウェアエンジニアリング」のドキュメントの章を読むことをお勧めします。何故、Google内部wikiを廃止したのか？などSREの探求ではサラッとしか触れられていないところについて書かれているので、興味がある方は是非読んでみてください。

SRE Kaigi 2025について

最後に、宣伝になってしまうのですが、来年開催予定のSRE Kaigi 2025について少し触れておきます。

SRE Kaigiは「More SRE！」をテーマに、SRE界隈がさらに盛り上がることを目指して開催されるイベントです。
今回が初開催になりますが、只今絶賛スポンサー様を募集しておりますので、何卒よろしくお願いいたします🙇