Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Sign up for free
Menu
Search
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Pricing
Search
Sign in
Sign up for free
リリース済にも関わらず何のドキュメントもなかったシステムの仕様書を書いてみた話
Search
ken
January 14, 2022
Programming
130
0
Share
Embed
Copy iframe code
Copy JS code
Copy link
Start on current slide
リリース済にも関わらず何のドキュメントもなかったシステムの仕様書を書いてみた話
ken
January 14, 2022
Transcript
32 slides
リリース済にも関わらず何のドキュメントもなかったシステムの 仕様書を書いてみた話 segami ken
今回のプレゼンで言う仕様書とは、 開発前の設計書というより、開発後運用フェーズにいく前に用意しておいたほうがよいドキュメントと いう位置づけ。
先月のある日 とあるアプリの追加機能の作成依頼が営業職の方から届いた。 追加機能は難しいものではなく、「多分そんなに日数がかからずにできると思います」と 返した。
とは言ったものの... 最近、そのアプリ全然触ってないなあ。 継続的に使っていただいているから、大きなバグは無さそうだけどどうやって実装したっ け?
なんとなく覚えていること • フロントエンド ◦ エンドユーザー向けの画面が存在する ▪ csvをアップロードする機能など • バックエンド ◦
画面に必要な情報を返すためのバックエンド APIが存在する ▪ アップロードされたcsvの名前やユーザーの名前を返す機能など • その他 ◦ アップロードされたcsvの内容を元にスクレイピングが実行されるところが別レポジトリに存在する
そもそも最近いつアプリのアップデートしたっけ...? ECRにpushした日付 (現在2022年1月) GitHubにpushした日付
何も覚えていない.... システムを作成した張本人なのにどうしよう... 今回は1人で作成したので自分しか覚えていない..
要件定義、基本設計、詳細設計のフェーズはチャットでのやり取りは残していたが、 開発後 正式な仕様書として何も残していなかった..
とりあえずローカル環境で動かしてみたり、 コードを読んでみよう..!
ローカル環境での動かし方もあまり覚えていない... コードも多くて読み解くのに時間がかかる...
システムに関する仕様書がないことのデメリット • ゴールが分からない問題 ◦ 誰のどんな課題を解決するためのシステムなのかが時間と共に忘れてしまう • チームメンバーの増減に対応できない問題 ◦ システムの使い方を忘れていたり、ローカル環境での動作手順がパッと分からず時間がかかる ◦
新しいメンバーが増えた時にも 1から説明しないといけなくなる • 追加機能やバグ修正に対応しづらい問題 ◦ システムの具体的な仕様を忘れていて、新たに機能を追加しようとする際に元々の仕様を無視して しまう恐れがある ◦ インフラの構成、DB構成、手動の場合のデプロイの方法などが分からずエラー原因の調査等に時 間がかかる
デメリット大きすぎる... 何はともあれ、 開発者向けに仕様書を書いてみました!
記載した項目 (読み手は開発者を想定) • システムが目指す姿 ◦ このシステムで解決したい課題 ◦ システムの目指すべきゴール ◦ このシステムでは対応しない問題
• システムの概要 ◦ 満たしている要件 ◦ 詳細な仕様 • 開発者に必要な情報 ◦ ローカル環境での動作手順 ◦ DBのテーブル構成図 (ER図) ◦ AWSの構成図 ◦ デプロイの手順 ◦ 現状残っている開発上の課題
要件?仕様?それぞれの定義は?
こちらのスライドを参照させていただきました。 https://speakerdeck.com/yasuoyasuo/enziniafalsetamefalsedokiyumentoli-ji-chu-jiang-zuo?slide=15
とはいえ文章の書き方も仕様書に記載した項目も自己流.. これで本当に良いのか?
まずビジネス文章の書き方を調べてみる
Google テクニカルライティングが参考になる > Every engineer is also a writer. という記述が印象的。
https://developers.google.com/tech-writing
文章の書き方の重要なポイント • 誰が読んでもただ一つの解釈にしかならないような文章の作成 ◦ 冗長な表現はできるだけ避けて、簡潔な文章を作成 ◦ コンテクストの擦り合わせ (必要に応じて必要な前提知識や背景を書き加える ) •
表記統一 ◦ 例えば 「読者」と「読み手」を統一する ◦ 箇条書きの際に文末に句点をつけるかどうかの統一 ◦ である調、ですます調の統一 • 文章の構造化 ◦ 見出し、段落、箇条書きを使用して文章全体の構造を一目で把握できるようにする • 結論ファースト • 事実と意見を分ける
テキスト校正くんを使ってみる テキスト校正くんというVisual Studio CodeのExtensionがある。 実際に使ってみると、たくさんの指摘をしてくれました。便利!
次に仕様書に記載すべき項目を調べてみる
の前に... そもそもシステムを作る際に必要なドキュメント(設計段階含めて) の全体像を理解したい
どうやら理想はこんな感じのよう • 要件定義 ◦ 要件定義書 • 基本設計 (外部設計) ◦ 業務フロー
◦ システム構成図 ◦ ER図、テーブル定義書 ◦ 機能一覧表 • 詳細設計 (内部設計) ◦ 画面遷移図 ◦ 詳細設計書 • プログラミング ◦ 補足でコメントを書く • 単体テスト ◦ 単体テスト仕様書 • 結合テスト ◦ 結合テスト仕様書
IPAのページを見てみる 要件定義の際に作るべきドキュメントのサンプル集 https://www.ipa.go.jp/sec/softwareengineering/tool/ep/ep2.html
数人で小規模のアプリを作るフェーズだと ドキュメント書き過ぎても費用対効果低そう.. (主観)
3人チームぐらいでソフトウェア開発する際の良さそうな塩梅 (仮説) • システムの目的、ゴールは最低限まとめる • Figmaでデザイン作る • ER図、インフラ構成は設計段階から図にして共有しておく (Draw.ioなど) ◦
変更があった場合、どうやって変更していく習慣、仕組みを作るかが課題 • API仕様の文章化にSwaggerを使用する、テスト書く ◦ 新規機能追加をする PRを作る際にテストの追加とドキュメントの更新もされていれば Approveする ルールにするなどにすることで、変更の仕組みも作りやすい ▪ Laravelを使用してバックエンド作る際に便利そうなライブラリ https://github.com/DarkaOnLine/L5-Swagger ◦ これらを書くことで機能の詳細ロジックや機能一覧を細かくドキュメントに記載する必要がなくなる
本題に戻る。仕様書に記載すべき項目を調べてみる
記載した項目を振り返ってみる 追記した項目を黄色文字で記載したが、元々のでも最低限は書けていたみたい リリースまで何のドキュメントがないという最悪の状態からでも、とりあえず以下の項目を書けば少しでも将来の自分を救うことができた。 そして仕様書を作成後、無事スムーズに追加機能の実装とリリースができた。 • システムが目指す姿 ◦ このシステムで解決したい課題 ◦ システムの目指すべきゴール
◦ このシステムでは対応しない問題 • システムの概要 ◦ 満たしている要件 ◦ 詳細な仕様 = 機能ごとの説明 ◦ 画面遷移図 • 開発者に必要な情報 ◦ ローカル環境での動作手順 ◦ DBのテーブル構成図 (ER図) ◦ AWSの構成図 ◦ デプロイの手順 ◦ 現状残っている開発上の課題
参考にした資料 仕様書の書き方 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
その他
秘密情報の管理 ローカルで動作確認する時に環境変数やcredentialファイルが必要なケースがあった 環境変数はAWS Systems Managerのパラメータストアで管理し、仕様書にはパラメータスト アのURLを記載するようにした その他GitHubにあげたくないが動作確認に必要なcredentialファイルなどは、Googleドライ ブで特定の事業部の人のみがアクセスできるフォルダにファイルを置いた。 仕様書にはそのフォルダへのURLを記載するようにした
ご静聴ありがとうございました
More Decks by ken
See All by ken
Accessibilityに興味が出てきた話
segamiken
0
120
Laravelに入門してみた
segamiken
0
120
Other Decks in Programming
See All in Programming
Materialが消えた日 〜真っ白なFlutterキャンバスにRenderObjectで絵を描く〜
umigishiaoi
0
170
Crash Auto Pipelines
veronikapj
1
440
あなたの await、OS まで届いてる? strace で覗く JavaScript の非同期
hasutosasaki
1
2.4k
自宅サーバはどこまで再現できるのか - Proxmox VE上のVM環境をIaCとバックアップで戻してみた
youto
0
430
SODA - FACT BOOK(EN)
sodainc
1
270
Coding with AI: How to trust the storyteller (AWS Community Day Adria, Ljubljana 2026)
slobodan
0
150
Spec-driven Development with AI
simas
PRO
0
2.3k
Scalaの型でマルチテナントの認可を守る
nextbeatdev
0
160
コード生成時代のAPI定義を支えるRequest Spec移行
pvcresin
0
290
学びを記事・スライド・Xへ高速展開する― AI-assisted Learning Loopで回すコンテンツ生成術
ochtum
0
220
Rails初心者がパスキーを実装してみて大変だったこと
ktombow
0
220
まずはコードより業務と向き合う:テーブル解体のためにPdMを呼んだ話
sakawe_ee
0
260
Featured
See All Featured
Git: the NoSQL Database
bkeepers
PRO
433
67k
Agile that works and the tools we love
rasmusluckow
331
22k
State of Search Keynote: SEO is Dead Long Live SEO
ryanjones
0
350
Information Architects: The Missing Link in Design Systems
soysaucechin
1
1.3k
Unsuck your backbone
ammeep
672
58k
Navigating Weather and Climate Data
rabernat
0
600
Un-Boring Meetings
codingconduct
0
500
How to Ace a Technical Interview
jacobian
280
24k
16th Malabo Montpellier Forum Presentation
akademiya2063
PRO
0
470
Dominate Local Search Results - an insider guide to GBP, reviews, and Local SEO
greggifford
PRO
0
410
A Guide to Academic Writing Using Generative AI - A Workshop
ks91
PRO
1
570
The Cost Of JavaScript in 2023
addyosmani
56
10k