スタートアップでのドキュメント運用の効用とやり方

達人プログラマーはドキュメントを開発プロセス全体と切っても切れないものとして捉えています。同じような作業を繰り返して行わず、また時間の無駄にならない方法で、ドキュメントを手近なところ（つまり可能な限りコード自身の中）に置いておくことで、簡単にドキュメントを作成できるようになるのです。
達人プログラマー

達人プログラマーに大きな影響を受け、DOGADOZO の開発が始まってから、ドキュメント整備に力を入れてきました。
この記事では、今の会社で行っているドキュメントの整備方法を簡単にまとめます。

ドキュメントの効用

個人的に最も大きいのは「同じことを何度も聞かれるというストレスが緩和されること」だと思っています。

プロダクト開発をしていると開発者とそれ以外の社員で、仕様に関する知識のギャップが大きくなり、相手のプロダクト理解度を探る必要があるため、フラストレーションにつながります。
ドキュメントがあれば、「まずはこれを読んでいただき、ここに記載のないことで不明点があればご質問ください」という流れに誘導しやすく、繰り返し同じことを説明するコストを削減できます。

また新しくメンバーが入ってきた際には、一からプロダクトをキャッチアップする必要があるため、ドキュメントがないとなかなかしんどいです。

DOGADOZO では以下の 2 種類のドキュメント整備をしています。

  • 開発以外の社員向け
  • 開発者向け

開発以外の社員向け

機能全体の仕様書

プロダクトの機能全体を Google Document にまとめています。
ドキュメントツールは他にもたくさんありますが(Notion とか良いですよね!)、「開発以外の社員にとって最も馴染みのあるもの」を使うのが良いと考えました。

Google Document では変更履歴の確認・コメント挿入・提案モードで修正などができ、特に今のところ不便は感じていません。
こういったドキュメントについては、プロダクトの詳細な設計に詳しい開発者が管理をするのが理想です。今の現場では僕がリリースのたびに、内容を更新し、他の社員にもメンテナンスを手伝ってもらう形で運用しています。

議事録

議事録には Dropbox Paper を使用しています。
こちらは僕が入社した当初から開発 MTG の議事録は Dropbox Paper を使うという方針でした。

Dropbox Paper はカジュアルにコラボレーションができ、Markdown で書きやすいですが、検索に弱いと感じています。
もっと良いのをご存知でしたら、教えてください。

開発者向け

コメント

コメントがなくても理解できるほど綺麗なコードであれば良いですが、現実的には数ヶ月前のコードを見返して「あれ、このコードなんだっけ…？」となることが時々あります。
自分が過去に書いたコードでもそうなりますから、チーム開発だとなおさらです。

レビューの段階で実装意図が伝わりづらいと感じたら、「実装意図」をコメントで記載するようにしています。
また実装に関する細かいやりとりを GitHub で行った際には、コメントの URL を記載したりすることもあります。(実際のやり取りをコメントで記載すると長くなり過ぎるため)

# @see https://github.com/…

コミットメッセージ

コミットメッセージについては、視認性をあげる目的で Anguler.js のドキュメントを参考にプレフィックスをつけるようにしています。

  • feat: 機能追加
  • fix: バグ改修
  • docs: ドキュメント
  • style: スタイル調整
  • refactor: リファクタリング
  • test: テスト
  • chore: 上記以外

参考: angular.js/DEVELOPERS.md at master · angular/angular.js

プレフィックスにはあまりこだわりないですが、できる限り詳細な情報をコミットメッセージには載せるようにしています。

GitHub の運用

  • Slack でのやりとりを転記する
  • 設計のやりとりは Issue で、実装のやりとりは PR で行う
  • Wiki は開発者向けの開発者向けドキュメントとして使用

Slack やりとりの転記

今の会社では Slack 無料プランを使用しているため、過去のやりとりを検索できなくなります。
重要なやりとりが消えてしまわないように、履歴が残り検索もできる GitHub にコメントとして、転記するようにしています。(スタートアップならではですかね..笑)

設計のやりとりは Issue で、実装のやりとりは PR で行う

コメントのやりとりを Issue・PR で役割分担しています。
これは後から検索しやすいようにするためです。

Wiki は開発者向けの開発者向けドキュメントとして使用

GitHub の Wiki は開発者向けのドキュメントとして、以下の内容を書き残しています。

  • トラブルシューティング
  • 要件定義の際に確認すべき事項

Wiki は「開発者が今まで経験してきた失敗を繰り返さないための注意事項や手順などを残す」ことが役割だと思っているので、未来の自分や他の開発者に寄り添う気持ちで書いています。

TwitterFB!

関連記事