tags
Android
author
category
android
mainImage
publishedAt
Feb 14, 2024
published
published
slug
newt-app-devdoc
authorDisplayName
Kazuho Hosoi
はじめに
こんにちは、令和トラベルで Android アプリエンジニアをしている細井です。
本記事では、以前 EM の吉田の記事 でも紹介されていた NEWT のアプリ開発で導入したドキュメンテーション “Dev Doc” について、より詳細にどういった経緯で、どのような運用をはじめたのかを赤裸々に紹介します。
なぜドキュメントを書くのか
私が Join した2023年9月頃、NEWT のアプリ開発チームでは以下のような、アプリ開発あるあるの問題が発生していました。
- 仕様の調整が、口頭や Slack の色々なスレッドで行われ、最終的な仕様が Slack なのか Figma なのか実装なのかを追いかけるのに時間がかかる
- 新しく Join したメンバー (私) が、既存仕様やロジックをコードからしか読み取れず、キャッチアップに時間がかかる
- 自身がキャッチアップできた範囲でしか実装しないため、仕様の考慮漏れが発生する
- QA 期間になって、iOS は実装してるけど、Android はまるまる実装してない箇所がある
- 過去、各プラットフォームそれぞれ異なる仕様で実装していて、何が正しいか分からない状況になった
これらの問題は、情報共有や合意形成といったコミュニケーションの問題だと捉えられるので、そういったコミュニケーションの土台となるツールとして、ドキュメンテーションの導入を考えはじめました。
何を書くのか
当初は Design Docs を導入しよう、という話もあったので、改めて Design Docs って何だっけというところから振り返りました。
Design Docs は Google 等でも導入 される、ドキュメント化〜メンバーとの共有・議論をするための手法です。
あくまで手法のため、書く内容としては必ずしも決まったフォーマットがあるわけではないですが、以下のような内容を記載することが多いようです。
- 目的・ゴール
- 敢えてやらないこと
- 検討した別の方法
- システムアーキテクチャ
- ドメイン設計
- API 設計
- データベース設計
- UI 仕様
- コード設計
- その他の考慮事項
- セキュリティ、プライバシー etc…
NEWT アプリ開発にあてはめて何を書くか考えた時、
- 要件定義の部分は、PdM がドキュメントを作成してくれる
- デザインデータとして Figma が存在しており、細かい文言なども定義してくれている
- アプリが使用する API の設計は、Backend 主導で、Github や Slack で仕様調整し、GraphQL のスキーマがマスター情報となっている
という前提があり、これらの内容は重複するため除外することにしました。
また、弊社の iOS/Android のエンジニアは PP (令和トラベルでは、業務委託メンバーを “プロ・パートナー”、略して “PP” と呼んでいます) のメンバー含め、1人で開発を任せられるレベルであることから、コーディングレベルでの設計のような内容も too much だと考え除外しました。
これは過去の経験から、クラス名やデータフローといったコーディングの素案まで書いてレビューが通ってから実装する、といった Design Docs の実体験からコストが重すぎる懸念もありました。
上記のとおり、除けるものを削ぎ落としていくと、課題を解決するために必要なものは、以下のような内容で、詳細仕様書に毛が生えたようなものでした。
- (実装で) やること
- 目的・ゴールはバックログに記載されてるので、明確になった実装スコープ
- (実装で) 敢えてやらないこと
- 実装スコープ外としたこと
- UI 仕様
- その他アプリの考慮事項
- イベントロギング、ディープリンク etc…
こういった詳細仕様は、コードを見た方が速かったり、最新であったりすると言われることもありますが、iOS/Android + Web と、複数プラットフォームで同様の機能を実装する場合、異なるプラットフォームのコードを正確に読み解くのは簡単ではなかったり、エンジニア職以外のメンバーと共有することを踏まえると、自然言語で書き起こすことにメリットはあると考えています。
タイトルにありながらも余談になりますが、「Design Docs と言われると変に難しく感じてしまう」「詳細仕様書と呼ぶのは何となく嫌」という話もあり、”あくまでエンジニアが実装するためのドキュメント” という意図で “Dev Doc” という呼び方になりました。
NEWT アプリ開発での運用
目的
改めて課題から解決したいことを考え、NEWT アプリ開発では以下を目的としてドキュメンテーションを運用することにしました。
- PdM、デザイナー、QA エンジニアと仕様の認識齟齬を防ぐ
- iOS ↔ Android 間での意図せぬ仕様差異を防ぐ
- 仕様・考慮漏れの早期発見
- 最新仕様への追従コストの削減
- メンバー間での知識共有
運用ルール
ドキュメンテーションが形骸化しないように、目的を意識しながらも、なるべくコストのかからないよう以下のような運用ルールを定めました。
- ある程度の規模のバックログの際に作成する
- スクラムスプリントのストーリーポイントが n以上で書くルール
- iOS/Android アプリエンジニアが作成し、アプリエンジニア以外が読んでも理解できないことも許容する
- アプリエンジニア間の認識齟齬が発生しないようにすることを優先する
- デザインのマスターデータは Figma とする
- デザインの変更に追従するためにドキュメントを更新するコストが高いため
- 作成したら、PdM、デザイナー、QA エンジニア含め、読み合わせを行い、各自の観点から考慮漏れや認識齟齬が無いかを擦り合わせる
- 作成時に細かい未確定事項があれば、この場で確認する
- 作成後、実装中に仕様の変更や追加があった場合は、ドキュメントを更新して変更したことを共有する
- リリース後は、ドキュメントのメンテナンスを終了する
- メンテナンスし続けることは非常にコストが高いため、あくまで実装時のドキュメントとして残す
テンプレート
ある程度の自由度は持たせつつも、スマホアプリ開発でよくある考慮漏れや記載漏れを防ぐ目的で、以下のような最低限のテンプレートを作成しています。
はじめに
- 関連ドキュメント
- バックログのドキュメントや、Figma などのデザインへのリンクを貼る
- やること、やらないこと
- このドキュメントのスコープを明確にするため、やること、やらないことを記載する
- やらないことは、要件定義や仕様調整の中ででてきた、このスコープではやらないことを記載する
- 検討したけど、やらないと意思決定したことを残すことで、今後同じ議論になることを防ぐ
UI 仕様
- このドキュメントでのメイン部分であり、バックログやデザインには記載されていない、以下のような詳細な UI 仕様含め記載する
- UI デザインの変更点
- API のどの値を参照して、どう表示するか
- エラーハンドリングのパターン
- iOS/Android それぞれでアーキテクチャや既存実装によって、コーディングレベルでの設計やロジック差異は発生しうるため、実装方法を縛りすぎないように、クラス名等、詳細すぎるコードのことは不必要に記載しない
その他考慮事項
- ログの変更
- Firebase などでのイベントロギングの追加・変更仕様を記載する
- Android では取得できているけど、iOS では取得できていない、といったことになりやすいところなので、イベントのトリガーやパラメータを明確にする
- ディープリンクの変更
- ディープリンクの追加・変更仕様を記載する
- 画面構成や検索条件の変更で、ディープリンクもあわせて変更が必要なケースもあるため明確にする
- API の変更
- このスコープで変更になる API の変更点を記載する
- API 設計について記載するわけではないので、API の変更が分かる Pull Request 等や API ドキュメントへのリンクを貼るだけでも OK
- リリース
- アプリの公開の前に、API、Web が先にリリースされている必要があるケースが多いため、リリースの順番を事前に検討し、記載する
- また、API の変更等で強制アップデートの必要がある場合も事前にチームでスケジュールを計画し、記載する
運用してみて
まだ数件しか作成していませんが、現時点では以下のような Good/More を感じています。
Good
- テキストに書き起こすことで脳内整理が進んだり、チームメンバーと擦り合わせするこで、考慮漏れの早期発見やモヤモヤの解消ができる
- 上記によって細かい仕様が明確になってることで、実装に集中しやすい
- QA フェーズでの致命的な抜け漏れや iOS/Android での仕様差異といったことが減少した（と思われる）
More (+ Next Action)
- それでも後工程での考慮漏れは発生する
- → 大きく観点が漏れていたことは、テンプレートが肥大化しない程度に拡充
- 複雑なロジックをドキュメントに書いた結果、実装者が実装方法が縛られたと感じてしまった
- → 実装レベルでの細かすぎる書き方をしない、実装によって変更の余地がある共通認識を作る
今後について
上記の Good のとおり、感覚的に良いと思える部分もありつつも、ドキュメンテーションコストに見合った成果が出ているかは（マネージャーが）検証していきながら、フォーマットや運用をアップデートしながら改善していきたいと考えています。
おわりに
本記事では、NEWT アプリ開発におけるドキュメンテーションについて紹介させていただきました。
ドキュメンテーションは、仕様を残すこと以上に、チームでの知識共有・合意形成の土台となるツールとして有効なので、しっかりしたドキュメント書かなければ！と肩肘張らずに、チームにあったミニマムな運用ではじめてみてはいかがでしょうか。
令和トラベルでは、技術的な知識や知見・成果を共有するLT会を毎月実施しています。発表テーマや令和トラベルに興味をお持ちいただいた方は誰でも気軽に参加いただけます。
2月はVoicyさん、タイミーさんと合同開催で、各社の異なる技術スタックについて勉強会を行います！
また、この記事を読んで会社やプロダクトについて興味を持ってくれた方は、ぜひご連絡お待ちしています！
フランクに話だけでも聞きたいという方は、カジュアル面談も実施できますので、お気軽にお声がけください。
それでは次回のブログもお楽しみに！Have a nice trip！！
