こんにちは。テクノロジー本部のyoshikawaです。好きなW3C Recommendation は RDF 1.1 Concepts and Abstract Syntax です。
会議やチャットでのやり取りの決定事項・議事録、アプリケーションや機能の設計書・仕様書、READMEなどなど...
LIFULLの開発現場においては、ソースコード以外にもこのように様々な文書の管理・蓄積(=ドキュメンテーション)を実施しています。
多くの開発者・メンバーがドキュメンテーションの重要性やその恩恵は理解はしているものの、なかなかうまく情報の蓄積・管理ができない、 その結果、本質的ではない調査に時間を取られてしまいDeveloper Experienceが下落してしまう。 このような課題を抱えているプロジェクトやチームは世の開発現場において少なからず存在すると思います。
LIFULLの開発現場にもこの課題は当てはまります。 私が参加しているバックエンド刷新プロジェクトではドキュメンテーションにまつわる課題を解決すべく様々な取り組みを行ってきました。
この記事では私が参加しているバックエンド刷新プロジェクトを中心に実施している、継続的なドキュメンテーションを可能にする仕組みについて紹介します。
バックエンド刷新プロジェクトについてはこちらの記事をご覧ください。Clean Architectureを採用しバックエンドAPI開発を行っています。
想定している対象読者
- ドキュメンテーションをうまく機能させるための仕組みやヒントを知りたい人
- 社内WikiやREADME(Markdownファイル)でのドキュメントの作成と管理に限界を感じている人
- GitHub Discussionsの活用事例を知りたい人
どうやってドキュメンテーションを実施しているのか
LIFULLでは主に社内Wikiツールを利用してドキュメンテーションを実施しています。 メンバーがエンジニアのみで構成されているチームでは専用GitHub Repositoryを作成しMarkdownファイルをバージョン管理したり、 GitHub Wikiなどの機能を活用しているケースもあります。バックエンド刷新プロジェクトもそのケースの一つです。 現在は主に社内Wiki、ドキュメンテーション専用GitHub Repository、そしてGitHub Discussionsの3つをツールとして活用しドキュメンテーションを実施しています。
ドキュメントの性質とツールの使い分け
ドキュメントの性質によって、バックエンド刷新プロジェクトでは以下のようにツールを使い分けています。 以下で挙げているツール以外にGitHub Wikiも利用していた時期もありました。記事の本題と逸れるため経緯は割愛しますがGitHub Repositoryへと移行しています。
- 社内Wiki: 技術要素が薄くエンジニア職以外が見ることを想定しているもの、便宜上社内Wiki内の機能を利用したいもの
- 例: プロジェクト憲章、Retrospective資料
- GitHub Repository: 技術的な内容に関する規約、ルール、ベストプラクティスや学習資料など、「決まりきったもの」
- 例: コーディング規約、推奨実装パターン、Clean Architecture学習資料
- GitHub Discussions: 技術的な内容に関するメモやログ、構想など、「とりあえず記録しておきたいもの」
- 例: アーキテクチャに関する規約やパターンの提案、決定事項のメモ(Architecture Decision Records)
このように社内Wikiは必要性が生じた際に利用し、なるべくGitHub上に情報を蓄積させていく運用をしています。
当初は通常のソースコード管理と同様に、GitHub Repositoryで全てのドキュメントのバージョン管理を実施していましたが、これからお伝えするような「辛さ」が生じてしまったために、 「決まりきったもの」はRepository内に、「とりあえず記録したいもの」はArchitecture Decision Recordsの考えの下、GitHub Discussionsに蓄積する運用に変更しました。
GitHub Repositoryだけでドキュメントを管理してみた結果と課題
どうやって運用してきたのか
当初はGitHub Repositoryのみで技術的なドキュメントを管理していました。 個人ブログや各種ブログサービスの記事管理と同じように、通常のソースコードと同様にドキュメント(.mdファイル)を管理するというものです。
ドキュメントが作成・更新されるまで
ドキュメントの作成や更新の際には、ドキュメントの体裁が崩れることや用語の表記揺れを防ぐためにtextlintというライブラリを利用してドキュメントのフォーマットを実施しています。
下記のように設定ファイルを作成し体裁や表記の揺らぎを防止しています。
version: 1 rules: - expected: Library patterns: - ライブラリ - expected: Application patterns: - アプリケーション - expected: CleanArchitecture patterns: - clean architecture - Clean architecture - Clean Architecture - クリーンアーキテクチャ - クリーンアーキテクチャー
ローカルではnpm script, pushした後もGitHub Actionsでtextlintを実行&規約指摘するように設定し、 文章の体裁やフォーマットの揺らぎを防ぎつつ、ドキュメントの作成・更新を実施してきました。
ドキュメント中の文章の体裁やフォーマットだけでなく、ドキュメントのファイル名やドキュメントの階層構造の適切さもレビュー時にチェックするようレビュー体制の運用もしてきました。
この一連の厳格なドキュメンテーション更新フローによって読者に優しく読みやすいドキュメントを提供できます。 しかし、厳格なドキュメンテーションのフローを変更の多いプロジェクトにおいて適用することはドキュメント提供者への負荷となり得ます。
浮上した課題: 書くのが「辛い」
ドキュメンテーションに対して課題を持ちながらも、開発者は人間なので構造化され整ったドキュメントを書くことが辛いということもあります。 実際に運用しているとちょっとしたドキュメントの変更をする際にもtextlintからの厳格な指摘をpassする必要があり、「文章を書く辛さ」が目立つようになりました。 textlintの設定を緩和すれば多少の改善になりますが、ドキュメントの品質は維持したいため根本的な解決にはなりません。
文章を書く辛さ以外にも、「階層構造を維持する辛さ」もまた見逃すことはできませんでした。 意気揚々とブログを始めて最初は丁寧に記事の階層構造やカテゴリ管理をしていたがやがて面倒になった、そんな経験を持ったことがある方もいるかと思います。
ドキュメンテーション不全が招くディストピア
ステークホルダーが多いため、仕様変更や実装規約、推奨実装パターンなどの変更をなるべく最新の状態に保つ必要があるという、バックエンド刷新プロジェクトの性質上、 変更の頻度の多さに乗じて膨れ上がるこの辛さは無視できるものではありません。
ドキュメントを書くことが辛くなると、ドキュメンテーション専用Repositoryを触る/見るのが辛くなります。
開発プロセスにおいて、往々にしてドキュメンテーションは優先度が低くなり、後回しにされがちです。
やがて優先度が低くて誰も更新したがらないドキュメンテーション専用Repositoryが出来上がります。
そして誰も更新しないのでRepository内のドキュメントは陳腐化し、ドキュメントにすべき知識は個人のナレッジとして埋没してナレッジの共有が機能不全に陥り、 挙句には調査工数として新規開発者にそのツケがのしかかることでしょう。
実際にはさほど深刻な状態にはなっていませんでしたが、「ちゃんとした文章を書くのが辛い」ことに起因してナレッジの共有が失敗することは無視できないリスクです。
解決策
開発者ガイドラインを敷くことで紳士協定的の名の下にドキュメンテーションを強制するのではなく、
そして、ドキュメントとして機能するような適度にまとまった文書を作成可能でありながら、ドキュメンテーションの辛さを解消できる別の仕組みを用意できないか？
それこそがGitHub Discussionsを利用したArchitcture Decision Records(ADR)です。
GitHub DiscussionsでのADR
ADRとは？
以下はThoughtworksのTechnology Radarからの引用です。
Much documentation can be replaced with highly readable code and tests. In a world of evolutionary architecture, however, it's important to record certain design decisions for the benefit of future team members as well as for external oversight. Lightweight Architecture Decision Records is a technique for capturing important architectural decisions along with their context and consequences. We recommend storing these details in source control, instead of a wiki or website, as then they can provide a record that remains in sync with the code itself. For most projects, we see no reason why you wouldn't want to use this technique.
バックエンド刷新チームでは以下のことに着目してADRの考え方をドキュメンテーションに取り入れました。
- 決定事項の経緯や背景を第三者が閲覧可能
- 軽量なドキュメンテーション
- 第三者が簡単にコメント、編集可能
元の定義ではアーキテクチャに関する決定事項やその背景を記録することに焦点を当てていますが、バックエンド刷新チームでは実装に関する事柄も含めアーキテクチャ以外の事柄でも記録しています。
GitHub Discussionsを採用する
プロジェクトメンバーも、ステークホルダーもエンジニアが中心であるため、GitHubが提供する仕組みを利用してADRを実現することは自然な流れでした。 そして、スレッド形式で簡単にドキュメントの作成、第三者の編集/コメントが可能であり、ドキュメントをカテゴライズ、タグ付け可能なGitHub Discussionsを採用しました。
以下はDDD(ドメイン駆動開発)におけるDomain Serviceを巡ってのADRの実例です。
なお採用当初、GitHub DiscussionsはBeta版でしたが2021年8月17日にBeta版から正式版になりました。
GitHub Discussions × ADRを実践してみた効果
意図していたドキュメンテーションの負荷削減に加え、コミュニケーションにおいて意図していなかった効果がありました。
とりあえず残しておきたいことのドキュメンテーションが楽になった
大事なことだけど、とりあえず書き殴りのメモで残しておきたい、埋もれがちなテキストチャット上でのやりとりを保存しておきたい、 といったことを気軽に残せるようになりました。 その結果、大事な情報が個人のナレッジとして埋没してしまう機会が減りました。
下記のように、様々な粒度・トピックの内容を気兼ねなく残せています。
よって、当初課題となっていた「文章を書く辛さ」はGitHub Discussions × ADRによって狙い通りに克服できました。
Repositoryにあるドキュメントの管理も楽になる
ADRを取り入れていなかった以前、日数が経ってからドキュメンテーションをする場合は何を書くべきか思い出す/書くべきことを関係者にヒアリングすることが必要であり、 Repository上に残しておきたいような体裁の整ったドキュメントを作成するコストが高くなっていました。 ADRとして「とりあえず」残しておいた情報があることで、そのようなコストが発生することを予防できます。
なお、RepositoryはDiscussionsを採用した後も「決まりきったもの」を残す場として活用し続けています。 事例こそ多くありませんが、Discussionsで記載された「とりあえず残したいもの」を「決まりきったもの」としてRepositoryに残すという運用を実施しています。
スレッドを階層構造ではなくラベリングやタグ付けで管理できる
ドキュメントを見つけやすくするためにもドキュメントに階層構造などのメタ情報を持たせることは重要です。 以前の運用ではドキュメントをディレクトリに格納し階層構造持たせていたため、やや管理コストがかかっていました。(ドキュメントの階層構造を変更するためにcommitする必要がある) GitHub Discussionsで管理した場合、カスタムのラベルやタグによって各スレッドを管理・検索できるため、ドキュメントのメタ情報の管理コストが低くなりました。
そのため、第二の辛さである「階層構造を維持する辛さ」も解決することができました。
予定外の効果: 部署間のコミュニケーションチャンネルが増えた
当初は意図していませんでしたが、GitHub Discussionsを採用したことによる恩恵もありました。 プロジェクト内でのADRとして利用してきましたが、プロジェクト外の方でも広く閲覧可能&コメント可能にしてあります。 そのため、プロジェクト外の方からのフィードバックをいただけるような機会が増え、ドキュメントの質を向上させることに繋がりました。
また、チャットツール(Slackなど)で発生した他部署からの質問対応のやりとりをGitHub Discussionに転載・蓄積・転用することでコミュニケーションコストの削減にも役立っています。
現在はバックエンド刷新チームがモデレーターとなり新バックエンド基盤(新BFF)の開発コミュニティを運営していますが、 今後は開発者が増え、社内開発者コミュニティとして醸成されゆくことを期待しています。
おわりに
以上がバックエンド刷新チームで実施しているドキュメンテーションです。 先日Beta版から正式版となったばかりということもあり、GitHub Discussionsは社外/社内どちらからの視点でもその採用事例は多くはないです。
しかしその効果は確かなもので、本記事で紹介したドキュメンテーションとしての用途の他にも、著名なOSSコミュニティでもコミュニケーションフォーラムとして利用されています。 ドキュメンテーションで悩む方、あるいはGitHub Discussionsの利点がわからない、といった方に本記事が参考になれば幸いです。
