VideoStepの飯盛です！VideoStepの開発チームについて発信してみようと思い、テックブログを始めてみました。
今後も更新をしていく予定なので、チェックしていただけると嬉しいです！
はじめに: Notionベースのドキュメント管理つらい
元々私達のチームではNotionでドキュメントを管理してました。プロダクトの仕様やコーディング規約などはそこに記述し、オンボーディングの際はそこを参照するようにしていました。
しかし以下のような課題に悩んでました
- メンテナンスされてない
- 仕様に変更があった場合にドキュメントの更新がされず、古い内容になっている。
- 簡単に追加・変更ができるため、似たような記述のものが散在する
- 複数の場所に似たような記述のドキュメントがあって、しかも書いていることが違う。
- 置き場所がバラバラでドキュメントがあることに気付けない。
この課題はどうにかしないと、どんどんドキュメントが散らかってしまうと感じていました。
GitLabのドキュメンテーションを真似てみることにした
ドキュメントが整備されているところを真似してみようと考え、 「GitLabに学ぶ 世界最先端のリモート組織のつくりかた ドキュメントの活用でオフィスなしでも最大の成果を出すグローバル企業のしくみ」 という書籍でもお馴染みGitLabを参考にしてみることにしました。
そこで、以下GitLabのリポジトリを覗いてみると、/doc 配下に様々なドキュメントが集約されていました。開発規約や抽象化の方針、機能の仕様など、開発に必要なあらゆる知識が書かれていました。
doc配下。api, architectureなどの各ディレクトリの中にドキュメントのmdファイルがあります
少し話がそれますが、Guidelines for reusing abstractions というページが、Service classやFinderなどの各クラスの設計、抽象化のルールについて書かれていて、Rails アプリケーションの構成を考える上でもめっちゃ参考になりました。
このようにリポジトリ内にすべて集約する方が、実装と一緒のプロセスで追加とレビューができるし、場所が一箇所にまとまって良いと思い、真似てみることにしました。
できたもの
構成
以下のようにリポジトリ直下にdocsディレクトリを置き、以下のような形にしています
docs
├── architecture
│ ├── infrastructure.md
│ └―– software.md
├── contributing
│ ├── getting_started.md
│ └―– contributing.md
├── specification
│ ├–– feature1.md
│ ├–– feature2.md
│ └–– ...
├── ubiquitous
│ └── table.md
└── infrastructure.md
リポジトリのREADME.mdには、docs配下の簡易的な説明とそのリンクのみを設置する形にして、網羅的に見れるようにしています
一部マスクしています
ドキュメントに書く内容
開発に必要なプロダクト固有の知識を色々と書いています。
開発に参加したばかりのメンバーがプロダクトについて分からないことがあったときに、コードだけではわかりにくいところを中心に書くようにしています。
中でも機能仕様については細かく書いていて、mermaidによる図解も交えながら説明しています。
mermaidによる図解の例
VideoStepの翻訳機能に関する記述を例にお見せします。
例えば↓のように対象となる言語や関連するテーブルを書いたり、
↓のように翻訳を実行するときのAPI, DB, 外部サービス(この場合はGoogle Cloud)の３者でのデータのやり取りをユースケース図で書いたりしています。
特にこのユースケース図については、外部サービスとのやり取りがあると特に重要視して書いています。
- いつ外部へリクエストを送るのか？
- リクエストの結果をどう保存するのか？
などはコードをじっくり読まないとわからない場合が多く、このドキュメントがあると理解しやすいと感じています。
しかし、まだ書き方の規約を決めているというわけではなく各個人に依存してしまっているので、ルールの整備がいりそうです。
ドキュメントのメンテはいつやるか
基本的に、機能追加をしたタイミングで必ず追加・更新をします。
ドキュメントをメンテしていく上でよくある問題として「書き始めたはいいけどメンテされない」というものがあると思います。
そのためいつ追加・更新するかのルールを決めないと必ず更新されなくなってしまうだろうという結論に落ち着いたので、スプリントプランニングの時点で必ず実装と同時にドキュメントの追加・修正の作業チケットを作るというルールを設けました。
現在私たちのチームはスクラム開発を行っており、毎スプリント（一週間）ごとにスプリントプランニングを行い開発チケットごとに作業項目の洗い出しを行っています。その中で必ず「ドキュメントの追加・修正をする」という作業が追加されるようにしています。
具体的にはNotionを使ってタスク管理を行い、以下のように「毎回やるタスクを生成」ボタンを作ってそこを毎回押す、というルーティンをとっています。
現状はドキュメントの追加とQAのタスクを毎回生成しています
このルールのおかげでドキュメントが更新されない問題は今のところ防げています 👍
嬉しい点
いっぱいありました 🙌
コードレビューと同じ流れでレビューができるので、一定の質が担保される
github上でコードと一緒にレビューが行われるため、間違った内容や誤解の生む書き方がされることが減りました。
オンボーディングのコストが減った
新しいメンバーがジョインしたとき、プロダクトの説明をリポジトリを見せながらできます。また、新メンバーが開発中もわからないときはまずその中のドキュメントを見て、それでもわからなければ他の開発者に聞くという流れをとれます。
これによりオンボーディングをする側もされる側もコストが減りました。
最新の仕様を見ながら実装のプランニングが出来るので、影響範囲を予測しやすい
今までスプリントのプランニング時に実装内容を検討している際、「そういえばこっちにも影響ありそうですよね…」みたいな会話が途中から出てきたり、なんなら実装するまで気づかなかったりといったことが起こっていました。開発者たちの記憶や経験頼りのプランニングになっていました。よくない…
しかしドキュメントが揃ってくると、それを見ながら実装内容をすり合わせられます。それにより、最新の仕様は何で、それがどのように変わるかという会話がしやすくなります。
それと、ドキュメントにはどのようなものを追加・修正するかということも議論していくと、今回開発する仕様で不明確だった点に気づけたりということもあります。
これで機能追加の実装をする前にどこを直せばいいかの検討がしやすくなり、考慮漏れが減らせていると実感しています(もちろんすぐに0にはできないですが)。
まだ悩んでいる点
どこまでドキュメントを書くか
どのくらいまで細かくドキュメントに記載すべきかは毎回悩んでいます。これもスプリントプランニング時にどんなものを書くかある程度合意を取っており、明確な基準があるわけではないです。
ただこれも、毎回議論することでどんな仕様か明確になるという良さがあると思うので、今のところはその都度話し合って決めるやり方で問題ないと思っています。
リポジトリが複数ある場合は完全に一つに集約できるわけではない
VideoStepの開発では、API, Webフロントエンド, モバイルなどでリポジトリを分けています。
そのためドキュメントの場所の置き場もリポジトリの数だけ増えてしまいます。
基本的には、
- フロントエンドのリポジトリ: 画面操作やUIに関する仕様
- バックエンドのリポジトリ: APIで行っているDB操作や外部APIとの通信に関する仕様
という方針で書いていっているのですが、サービスの共通仕様として知っておきたい知識などはどちらのリポジトリにも書いておきたいので、同じ内容を複数箇所に書かないといけないです。
今の規模であればそれを許容していますが、辛くなったらドキュメント用のリポジトリを作るなどした方がいいかもしれません 🤔
まとめ・所感
github上でプロダクトに関するドキュメントを管理してみたら結構いい感じという話でした。
mermaidによる図の描画や、仕様の説明を0から書くのは結構骨が折れますが、ChatGPTやCursorを駆使すればだいぶすんなりできました。
それもあって今回紹介したやり方はうまくやれているかもしれません。
最後に
現在、VideoStepのエンジニアチームは少人数です。この機会を活かして、ドキュメント作成を全員の習慣にし、チームの文化として根付かせたいと考えています。
これにより、全員がドキュメントを作成し、参照するようになり、属人性がないチームを作れるといいなと思います 💪
まだ運用を始めたばかりなので、実践しながらルールを見直していく予定です。
この取り組みが皆さんの参考になれば幸いです！
株式会社VideoStepのエンジニアによるテックブログです。「映像で卓越した技術を未来と世界へ繋ぐ。」をミッションにVideoStepというプロダクトを開発しています！
Discussion