リリース済にも関わらず何のドキュメントもなかったシステムの仕様書を書いてみた話

Transcript

1. リリース済にも関わらず何のドキュメントもなかったシステムの 仕様書を書いてみた話 segami ken
2. 今回のプレゼンで言う仕様書とは、 開発前の設計書というより、開発後運用フェーズにいく前に用意しておいたほうがよいドキュメントと いう位置づけ。
3. 先月のある日 とあるアプリの追加機能の作成依頼が営業職の方から届いた。 追加機能は難しいものではなく、「多分そんなに日数がかからずにできると思います」と 返した。
4. とは言ったものの... 最近、そのアプリ全然触ってないなあ。 継続的に使っていただいているから、大きなバグは無さそうだけどどうやって実装したっ け？
5. なんとなく覚えていること • フロントエンド ◦ エンドユーザー向けの画面が存在する ▪ csvをアップロードする機能など • バックエンド ◦ 画面に必要な情報を返すためのバックエンド APIが存在する ▪ アップロードされたcsvの名前やユーザーの名前を返す機能など • その他 ◦ アップロードされたcsvの内容を元にスクレイピングが実行されるところが別レポジトリに存在する
6. そもそも最近いつアプリのアップデートしたっけ...？ ECRにpushした日付 (現在2022年1月) GitHubにpushした日付
7. 何も覚えていない.... システムを作成した張本人なのにどうしよう... 今回は1人で作成したので自分しか覚えていない..
8. 要件定義、基本設計、詳細設計のフェーズはチャットでのやり取りは残していたが、 開発後 正式な仕様書として何も残していなかった..
9. とりあえずローカル環境で動かしてみたり、 コードを読んでみよう..！
10. ローカル環境での動かし方もあまり覚えていない... コードも多くて読み解くのに時間がかかる...
11. システムに関する仕様書がないことのデメリット • ゴールが分からない問題 ◦ 誰のどんな課題を解決するためのシステムなのかが時間と共に忘れてしまう • チームメンバーの増減に対応できない問題 ◦ システムの使い方を忘れていたり、ローカル環境での動作手順がパッと分からず時間がかかる ◦ 新しいメンバーが増えた時にも 1から説明しないといけなくなる • 追加機能やバグ修正に対応しづらい問題 ◦ システムの具体的な仕様を忘れていて、新たに機能を追加しようとする際に元々の仕様を無視して しまう恐れがある ◦ インフラの構成、DB構成、手動の場合のデプロイの方法などが分からずエラー原因の調査等に時 間がかかる
12. デメリット大きすぎる... 何はともあれ、 開発者向けに仕様書を書いてみました！
13. 記載した項目 (読み手は開発者を想定) • システムが目指す姿 ◦ このシステムで解決したい課題 ◦ システムの目指すべきゴール ◦ このシステムでは対応しない問題 • システムの概要 ◦ 満たしている要件 ◦ 詳細な仕様 • 開発者に必要な情報 ◦ ローカル環境での動作手順 ◦ DBのテーブル構成図 (ER図) ◦ AWSの構成図 ◦ デプロイの手順 ◦ 現状残っている開発上の課題
14. 要件？仕様？それぞれの定義は？
15. こちらのスライドを参照させていただきました。 https://speakerdeck.com/yasuoyasuo/enziniafalsetamefalsedokiyumentoli-ji-chu-jiang-zuo?slide=15
16. とはいえ文章の書き方も仕様書に記載した項目も自己流.. これで本当に良いのか？
17. まずビジネス文章の書き方を調べてみる
18. Google テクニカルライティングが参考になる > Every engineer is also a writer. という記述が印象的。 https://developers.google.com/tech-writing
19. 文章の書き方の重要なポイント • 誰が読んでもただ一つの解釈にしかならないような文章の作成 ◦ 冗長な表現はできるだけ避けて、簡潔な文章を作成 ◦ コンテクストの擦り合わせ (必要に応じて必要な前提知識や背景を書き加える ) • 表記統一 ◦ 例えば 「読者」と「読み手」を統一する ◦ 箇条書きの際に文末に句点をつけるかどうかの統一 ◦ である調、ですます調の統一 • 文章の構造化 ◦ 見出し、段落、箇条書きを使用して文章全体の構造を一目で把握できるようにする • 結論ファースト • 事実と意見を分ける
20. テキスト校正くんを使ってみる テキスト校正くんというVisual Studio CodeのExtensionがある。 実際に使ってみると、たくさんの指摘をしてくれました。便利！
21. 次に仕様書に記載すべき項目を調べてみる
22. の前に... そもそもシステムを作る際に必要なドキュメント(設計段階含めて) の全体像を理解したい
23. どうやら理想はこんな感じのよう • 要件定義 ◦ 要件定義書 • 基本設計 (外部設計) ◦ 業務フロー ◦ システム構成図 ◦ ER図、テーブル定義書 ◦ 機能一覧表 • 詳細設計 (内部設計) ◦ 画面遷移図 ◦ 詳細設計書 • プログラミング ◦ 補足でコメントを書く • 単体テスト ◦ 単体テスト仕様書 • 結合テスト ◦ 結合テスト仕様書
24. IPAのページを見てみる 要件定義の際に作るべきドキュメントのサンプル集 https://www.ipa.go.jp/sec/softwareengineering/tool/ep/ep2.html
25. 数人で小規模のアプリを作るフェーズだと ドキュメント書き過ぎても費用対効果低そう.. (主観)
26. 3人チームぐらいでソフトウェア開発する際の良さそうな塩梅 (仮説) • システムの目的、ゴールは最低限まとめる • Figmaでデザイン作る • ER図、インフラ構成は設計段階から図にして共有しておく (Draw.ioなど) ◦ 変更があった場合、どうやって変更していく習慣、仕組みを作るかが課題 • API仕様の文章化にSwaggerを使用する、テスト書く ◦ 新規機能追加をする PRを作る際にテストの追加とドキュメントの更新もされていれば Approveする ルールにするなどにすることで、変更の仕組みも作りやすい ▪ Laravelを使用してバックエンド作る際に便利そうなライブラリ　 https://github.com/DarkaOnLine/L5-Swagger ◦ これらを書くことで機能の詳細ロジックや機能一覧を細かくドキュメントに記載する必要がなくなる
27. 本題に戻る。仕様書に記載すべき項目を調べてみる
28. 記載した項目を振り返ってみる 追記した項目を黄色文字で記載したが、元々のでも最低限は書けていたみたい リリースまで何のドキュメントがないという最悪の状態からでも、とりあえず以下の項目を書けば少しでも将来の自分を救うことができた。 そして仕様書を作成後、無事スムーズに追加機能の実装とリリースができた。 • システムが目指す姿 ◦ このシステムで解決したい課題 ◦ システムの目指すべきゴール ◦ このシステムでは対応しない問題 • システムの概要 ◦ 満たしている要件 ◦ 詳細な仕様 = 機能ごとの説明 ◦ 画面遷移図 • 開発者に必要な情報 ◦ ローカル環境での動作手順 ◦ DBのテーブル構成図 (ER図) ◦ AWSの構成図 ◦ デプロイの手順 ◦ 現状残っている開発上の課題
29. 参考にした資料 仕様書の書き方 https://qiita.com/ko1/items/9f5f1a2683ea54f12362 design-doc-template https://github.com/mercari/production-readiness-checklist/blob/master/docs/refere nces/design-doc-template.md
30. その他
31. 秘密情報の管理 ローカルで動作確認する時に環境変数やcredentialファイルが必要なケースがあった 環境変数はAWS Systems Managerのパラメータストアで管理し、仕様書にはパラメータスト アのURLを記載するようにした その他GitHubにあげたくないが動作確認に必要なcredentialファイルなどは、Googleドライ ブで特定の事業部の人のみがアクセスできるフォルダにファイルを置いた。 仕様書にはそのフォルダへのURLを記載するようにした
32. ご静聴ありがとうございました