こんにちは matinana です。 融資型クラウドファウンディングのサービス開発を行っています。 今日は、来年 3 人目のエンジニア¹をチームに迎えるにあたり準備しているドキュメントの話をします！

この記事は**CAMPFIRE Advent Calendar 2021**の 13 日目の記事です。

本記事の目的

この記事では、小さな開発チームである自分たちが用意している（or 用意しようと思っている）開発関連のドキュメントを共有することで、

• 同じような他の小さなチームの方にとって
• 明日から開発チームに入るドキドキのエンジニアにとって

「こういう情報があれば・分かれば」不安なく開発進められそうだな！という指針の一つになればと思っています 😊

また、ドキュメントを準備している自分たちにとっても、「なんでこのドキュメントって必要なんだっけ？」という問いへの整理の意味も込めています。

目次

1. オンボーディングドキュメント 2. 日々の業務に関するドキュメント 3. 開発環境に関するドキュメント 4. 仕様に関するドキュメント 5. アーキテクチャ・規約に関するドキュメント

1. オンボーディングドキュメント

まずは、入ってきたメンバーへのオンボーディングドキュメントです。

CAMPFIRE では コミュニケーションパートナー制度など、HR 部門を主体としたオンボーディングサポートが大変充実しているのですが、このパートでは開発側で準備しようと考えていることを共有します。

ちょうど先日、新メンバーとの顔合わせがあったのですが、**「チームに貢献出来るか？」**という点が一番の不安のようでした。

私自身も、入社時はこの不安が一番大きかったので、まずはこの不安を少しでも減らせるように

• 一定期間で目標にする状態を具体化
• それをフォロー出来るためのヘルプ環境があること

上記２つを初めに共有することが大切だなと考えています。

1. 一定期間で目標にする状態を具体化

入ってきたメンバーが迷わずに前に進めるように、チームにジョインしてから一定期間で期待する動きや具体的なタスクの内容をドキュメントとして共有します。

具体的には

• 一週間で期待する動き
• 一ヶ月間で期待する動き
• 上記期間で担って貰うタスクがどんなタスクになるのか

上記をドキュメントにまとめます。

一週間や一ヶ月でどうなっていればよいのか？その時にどういうレベルのタスクと向き合うことになるのか？

これを事前に把握出来ることで、「今日何やれば良いんだろう？」「明日や来週はどんな仕事してるんだろう？」という不明瞭な不安を取り除く事ができ、「この実装どうすれば良いんだろう？」という明確な答えが出る悩みのみが発生する環境を目指しています。

2. 定めた目標を本人とチームが一丸となって達成出来るサポートの仕組みを明示化

目標や取り組むタスクが具現化出来ても、まだチームに入ったばかり。当然わからないことや不安なことは沢山出てきます。

そういう際に悩みを拾い上げることが出来る環境が大切ですよね！

具体的には下記の仕組みで、当人からとチーム内からの双方向による困りごとの拾い上げが出来ればと考えています。

slack チャンネル

コミュニケーションのベースとなるスラックでは、開発チャンネル以外にも下記の 3 つのチャンネルを用いて困りごとの拾い上げを出来るように考えています。

1. プロダクト名_help チャンネル

• Dev＆Biz のプロダクトメンバーが入っている質問用チャンネル。

事業についてやドメイン知識など、チャンネル名にあるように困った時に dev 以外の内容も聞ける場所です。

2. 個人のオンボーディング用質問チャンネル

開発チャンネルや help チャンネルなど他チームの方など普段関わらない人が多く存在しているチャンネルで質問がしずらかった経験はないでしょうか？(僕はありますｗ) ここは日々顔合わせをする開発メンバーだけが入る新メンバー専用の質問チャンネルです。

ここでは、新しい仲間からの質問だけでなく、既存メンバーから「xx は大丈夫そう？」とメンションを投げるなど、新メンバーにとって一番安心して困りごとを解消出来るチャンネルに出来ればと考えている場所です。 新メンバー専用のページではありますが、将来的には公にすることで、このページにオンボーディング時の知見が溜められることを予期しています。

3. 個人の分報チャンネル

ここはオンボーディング用ではなく、個人が twitter のように何でも投稿可能な分報チャンネルです。困りごとの確認だけでなく、個人の気分転換や吐け口になることも想定している場所です。

夕会

チーム内の MTG は朝会もありますが、その日悩んだことをその日のうちに解消をモットーに、夕方に困りごとやその日一日の動きをすり合わせする MTG を行います。 やっぱり、不安を溜めたまま仕事を終えてもスッキリしないですもんね。 今のチームにはない仕組みですが、新メンバージョインと同時に始めようとチーム内で画策しています。

2. 日々の業務に関するドキュメント

こちらでは日々働く上で必要そうなタスク管理とコミュニケーション関連の情報の 2 つをまとめています。

1. タスク管理の方法

私たちのサービスは金融系のサービスなので、法律や制度に沿った機能開発が必要になります。

開発側だけで仕様が決定出来ることは多くなく、ビジネスサイドやコンプラサイドとの入念なすり合わせが必要になってきます。

そのため、開発チーム内でのやり取りや、ビジネス側とのやり取りなど、場面場面で利用するツールを 3 つに分けてタスク管理や仕様策定を行っています。

何をどのように利用すればよいのかをドキュメントとしてまとめることで、すり合わせ時のミスコミュニケーションが生まれないように基本方針を設定しています。

1. Noiton

大きめのタスクで todo に落とし込む前の PdM や biz 側とのすりあわせや確認で使う

2. Github issue

開発側でのコードを用いた仕様設計のすり合わせでのみ使う

3. asana

具体的な todo 管理 or 将来的なタスクのバックログ管理で用いる

• issue や Notion で仕様が固まったもの
• 仕様は確定していないが、将来的に対応が必要なもののバックログ

上記 3 つのツールの具体的な使い方（タスクのラベリングやスケジューリング)や、課題抽出から機能の本番反映までどういうプロセスで進んでいくのか？

上記などの細かい部分は書くとそれだけで 1 つの記事になってしまいそうなので割愛しますが、タスク管理の方法を明示化することで、

• すり合わせ内容がアチコチに散らばってしまう
• フォーマットがばらばらになってしまう

上記のような問題が起きにくい形を最低限整えようと考えています。

2. コミュニケーション情報のまとめ

開発以外にも多くのメンバーが関わっているため、誰と何をどこですり合わせるのか？ということも大切な考え方になってきます。

そこで、開発関連の slack チャンネルもそれぞれ一覧化しています。

具体的には

• 開発業務全般
• コード・デプロイ関連
• 通知関連
• 障害関連
• デザイン関連

上記に分けて内容をまとめています。

また、開発メンバーはもちろん、開発時に関わる非開発メンバーのリストも作成することで、チームジョイン時に悩みがちな**「これって誰に聞けばよいの？」**という疑問を解消する手助けになればと考えています。

これらの内容は、働き始めれば徐々に把握出来るものですが、あえて明示化することでチャンネルや個人の責務の切り分けを行い情報の集約化やミスコミュニケーションを防ぐ役割にもなります。

#3. 開発環境に関するドキュメント

こちらでは開発環境構築やデプロイフローなど機能開発以外の部分の開発ドキュメントをまとめています。

新メンバーが触れる内容としては、下記のようなものを準備しています。

• 開発環境構築

  • mac や docker などでの環境構築のやり方
  • つまづきポイントの解説
  • テストやリントなどのコマンド紹介

• デプロイ方法

  • 一連のデプロイプロセスの説明
  • ssh 接続を用いたコンソールでの動作確認
  • エラー発生時の各種対応方法

• 環境変数関連

  • env ファイルの内容
  • CI 上での環境変数の設定方法

• 各環境の使い方

  • ステージングや QA など各環境の使い方
  • 環境独自の制限や動作確認時に注意すべき点
  • QA での seed 要件

• インフラ関連

  • インフラ構成図
  • VPN 関連
  • DB バックアップに関して

これらは大変重要な内容ですが、一度作成されたものがアップデートされずに残りがちな内容ですので、新メンバーがジョインした際に、気になった点や不足している点をアップデートして貰い、出来る限り最新の情報に保てるように努めようと考えています。

#4. 仕様に関するドキュメント

仕様に関するドキュメントは特段新メンバーのために準備しているものではありませんが、それがしっかりあることで、新メンバーが過去の仕様ドキュメントを参考にドキュメント作成ができます。 それにより、チームのドキュメントの質や様式を担保出来ることを目的にしています。

具体的な内容を共有するとそれだけで記事がいくつか書けてしまうので、大まかな仕様の管理方法と最近はじめた仕様まわりの面白い取り組みを紹介させてください。

1. 仕様のおおまかな管理方法

主な切り口としては下記のような形で仕様をまとめています。

ビジネスルール

各機能の仕様を考える際の前提条件や法的なルールや制約、考え方などをまとめる場所。 ここに記載の内容を実装＆変更する場合は、ビジネスサイドやコンプライアンスの確認が必要になる部分です。

サービスの根幹機能のフロー図・一覧図**

サービスの根幹になる複雑な機能をステータス遷移図や一覧表など miro やエクセルで図表化して管理しています。 複雑な仕様の場合、テキストベースの仕様ではどうしても理解が難しいので、図表化することで理解の深化を意図しています。

各種機能の仕様をまとめるページ

各種機能の仕様を具体的にテキストでまとめたページ。 たとえば「CSV で出力される法的なデータの出力機能」に関してのページの場合は、

• そもそもその機能は何のための機能なのか？
• 出力タイミング
• 出力方法
• 出力の対象者
• 出力されるデータ
• 関連テーブル情報
• 仕様すり合わせ時の MTG やドキュメント
• 関連する asana

上記のようなデータを機能追加時に残すことで、ビジネスサイドからの急な問い合わせ時にも迅速に対応出来る情報をまとめています。

メール・通知・バッチ処理

システム上の仕組みによって自動で発生する処理に関して、オペレーション対応を行う人達でもわかりやすい形で内容や発生タイミングなどをまとめています。

各仕様と同じく、開発者としてはコードを読めば把握出来る部分ですが、非開発の人でもわかる形でまとめることで、開発側での仕様確認も随分と楽になっています。

2. プロダクトワークシュミレーション

プロダクトワークシュミレーションという開発側と運用側でサービスの全機能を一つずつ振り返る MTGも今年の後半になってから行っています。

開発時だと既存機能に関しては

• テストデータによる動作確認
• 開発側が想定している動かし方での動作確認

上記を行いがちです。

しかし、意図せぬ挙動になった際に運用側に内容を確認すると、

• 開発側が想定していない動作で機能を使っている
• 仕様では想定していない例外データが生まれる運用を行っている

上記のようなケースが発生していることもあります。

こういった状態を対応せずに放置しておくと、将来的な負債や障害に繋がりかねません。

そこで、サービスに関する全ての機能を Dev と Biz の両方集めて一週間に 1~2 機能ずつで動かしてみる会を行うことにしました。

すると、出るわ出るわ改善点という状態で、サービスの質向上にめちゃくちゃ寄与しています。

また、*+その会自体を録画している**ことで、新メンバージョイン時や運用側への対応確認時などの参考資料としてもすごく有益になっているので、ぜひ皆さんの会社でも試して頂きたい取り組みとして紹介させて頂きました！

5. アーキテクチャ・規約に関するドキュメント

アーキテクチャ・仕様に関しては新メンバーが入った時にチームでの規約や考え方を共有することで、

• 属人化しない保守性の高いコードになること
• 実装の考慮漏れがないかを考える指針

上記の目的になると考えて準備しています。

具体的には下記のようなものをまとめています。

各種コーディング規約

各フレームワークが提供しているものを推奨。 たとえば、Nuxt 部分の場合はスタイルガイドの優先度 A は必須で守ろうという意識付けを行っています。

テスト規約

• 何をテストするべきなのか？という指標 たとえば、E2E テストに関しては機能別にサービスレベルを定義している中で「不具合をおこしてはいけない機能」に関するものは書こう！という意識を共有しています。
• テストをどう書くべきなのか？という指標 たとえば、Rspec の場合はこちらのスタイルガイドに則って書こうと共有しています。

アーキテクチャまわり

ディレクトリ構造など。 たとえば、ビジネスロジックの閉じ込め先として workflow というディレクトリを切っていますが、

• どういう時に workflow を使い
• それはどういうパターンを実装の基本形とするのか

上記のようなプロダクト独自の設計を明示化しようと考えています。

終わりに

5 つの項目に分けて新メンバーがジョインする際に準備しているドキュメントに関して見てきました。

書いてみて思うことはこれらは**「新メンバーのため」ではなく、「チームのため・プロダクトのため」のドキュメントであり、まさしく自分のためになるドキュメント**だと感じたということです。

ドキュメントを作るということは、その情報にアクセス出来るという意味だけでなく、その情報が他の意思決定の指針にもなるということでもあります。

実際、この記事を書くことで、改めて準備するべき内容の意味やまとめ方を「もっとこうしてみよう」とブラッシュアップすることが出来ました。

この記事が、皆さんのプロダクトチームのドキュメントをより良い物に昇華させる指針の一つになることが出来れば嬉しく想います 😊

Happy Hacking! & Writing!

(謝辞) 記事中のイラストはすべてソコスト様からお借りしています。素敵なイラストありがとうございました 🙏