概要
定型的な システム開発 では以下のような設計書が使われる。
- システム要件定義
- システム方式定義
- ソフトウェア要件定義
- ソフトウェア方式設計
- ソフトウェア詳細設計
しかしそれ以前に 開発者目線、開発者発信で顧客に提案する概要資料を作りたい ケースがある。あるいは就職活動時の自身のポートフォリオを採用担当に説明することも同様かもしれません。
オードリー・タンがコード書く前にまずreadme.txtを書く話、Yahoo!がプロダクト開発の最初にプレスリリースから作る話、自分が前職で商品企画する際にまず広告から考えていた話、どれも明確なゴールイメージをまず確定させて必要要件を定義していくという意味で全部共通の考え方
— 菅俊一 / Syunichi SUGE (@ssuge) February 2, 2021
なんて話も。
技術とマーケティングのちょうど中間、開発者と顧客との意思疎通の橋渡しを行い、後の工程での双方の認識違いを少しでも無くすことを目指したい場合、想定読者をコンサルタントや営業、顧客、非技術者としたい 場合など。ここではそれを「提案書」と呼び、以下、どういった内容を網羅するとよいのかをまとめます。
テンプレート
当記事の結論です。
# 開発者が考える提案書テンプレート (markdown版)
## アジェンダ
- 提案の対象となる想定ペルソナ
- 提案の背景となる現状認識
- 提案の主題
- 提案への解決策
- 期待される効果について
- 費用
- スケジュール
- 体制図、関係者
## 提案の対象となる想定ペルソナ
## 提案の背景となる現状認識
### 事実1
### 事実2
### 事実3
- 具体的説明
- 具体的説明
- 具体的説明
## 提案の主題
一言で
## 提案への解決策
業務フローに落とし込んで説明
## 期待される効果について
- 定量的効果を想定して書く
## 設計概要
- のちの工程で設計自体は行えば良いので、ここでは想定読者、非技術者を意識し簡潔に。
## 費用・スケジュール概要
- 必要に応じて。
## 体制図、関係者
- 必要に応じて。この課題への追加の情報を誰にコンタクトすればよいかを明示する
開発者が考える提案書テンプレート (markdown版) 具体例
以下、テンプレートに沿って書くべき内容を具体的サンプルとともに説明してみます。
５Ｗ１Ｈを意識すると、良いです。
アジェンダ
## アジェンダ: 「朝寝坊」
- 提案の対象となる想定ペルソナ
- 提案の背景となる現状認識 「朝寝坊という問題を解決する」
- 提案の主題
- 提案への解決策
- 期待される効果について
- 設計概要
- 費用・スケジュール
- 体制図、関係者
以上、これから記載していく項目そのままです。「朝寝坊」...わかり易い例を考えた結果アジェンダのサンプルとしてややふざけたタイトルにしてしまいましたが、解決したい問題のテーマを表現します。
提案の対象となる想定ペルソナ
## 提案の対象となる想定ペルソナ
- リモートワーク中のソフトウェアエンジニア
誰が？という、ペルソナ。
こちらもそのままですが、具体的に想定ユーザ、ペルソナが明確な方が書きやすいですし、想定読者へイメージの橋渡しもしやすくなります。
提案の背景となる現状認識
## 提案の背景となる現状認識 「朝寝坊という問題を解決する」
### 事実1 - 朝寝坊をすると仕事のスタートが遅れる
- 朝寝坊により起きると即デイリースクラムの時間となることが起こる
- 会議に無防備で臨むことによりその日のTODO整理がままならない
- チームでの今日の自分の役割を会議で認識することになり「それをどう解決していくか」という重要なトピックの整理がスクラム内でおろそかになる
### 事実2 - 朝寝坊をすると仕事の終了が遅れる
- 事実1の問題により仕事を進めながら自己解決しなければならなくなる
### 事実3 - 朝寝坊をすると翌朝の朝寝坊を引き起こす
- 事実3の問題により仕事の終了、就寝が遅れるため翌朝の朝寝坊を引き起こす
いつ、どこで、どのように、そして、何故？
具体的に現状認識、課題を「事実に基づいて」書きます。ペルソナをよく観察、ヒアリングできていると書きやすいと思います。
提案の主題
## 提案の主題
絶対に朝寝坊を許さないタイマーアプリケーション「徹夜くん」
主題なので端的に伝わるように書くと良いです。タイトルや命名はソースコードのメソッド同様、大事です。
提案への解決策
## 提案への解決策
一晩の徹夜を支援することで朝寝坊を起こさない目的を達成し、現状の事実として説明したような負のサイクルを断つ。寝ることを許さないアプリケーションを作成する。
開発する製品・サービスでどのように現状認識に示した内容を解決しようとしているのか、書きます。
期待される効果について
## 期待される効果について
- ここ1番のプロジェクトの山場となるタイミングでペルソナが力を発揮するために用いる。
- 朝寝坊を回避すれば、仕事の終了を早めることができ、さらに翌朝の朝寝坊も回避する効果が期待できる。
得られる利点、効果を具体的に書きます。
設計概要
## 設計概要
- 場所を問わず用いることができるモバイルアプリを想定。
- タイマーアプリケーションは既に世の中に多数存在するのでそのフレームワークを応用する。
- 想定ペルソナ「リモートワーク中のソフトウェアエンジニア」を鑑みてマルチプラットフォーム対応とする。
開発者的に最も書き込みたくなってしまう項目ですが、今回のこの資料の目的としてはあくまで概要にとどめます。非技術者にもわかりやすく伝わることを主目的に、解決したい主題を補足する設計が網羅できていれば良しとします。
費用・スケジュール概要、体制図、関係者
## 費用・スケジュール概要
- 無償のIDE, OSSのフレームワークを用いる。Flutter等想定。詳細は設計資料を別途用意する。
## 体制図、関係者
- （コンタクト先の例）https://e99h2121.github.io/
最後の2項目は、あくまで補足的なものです。
以上を携え、我々得意の詳細な設計書は、これをベースに書いていく。
レビューサイクルを各ステークホルダーとまわすための、後々のアジャイル開発にも有用なツールになります。
c.f. PRD (Product Requirements Document，プロダクト要件定義書)
PRD，プロダクト要件定義書 については以下のようなテンプレートがあり、こちらも参考になる。
- 概要
- 背景
- 製品原則
- スコープ
- 対象ユーザー
- ユースケース
- 市場分析
- 競合分析
- 機能要求
- UX要求
- システム要求
- セキュリティ要件
- プライバシー要件
- パフォーマンス要件
- リリーススケジュール・マイルストーン
- マーケティング計画
スタートアップのための製品要求仕様書(MRD & PRD)の書き方
はじめてのPRD
初めて書くPRD（プロダクト要求仕様書）
c.f. インターナル・プレス・リリース
Amazon社ではインターナル・プレス・リリース という呼び方でフォーマットがあるようだ。
#20『アマゾン流インターナル・プレス・リリースの書き方』（海外記事紹介） 引用
・インターナル・プレス・リリース（社内用）のフォーマット
- Heading（大見出し）：ターゲット顧客が理解できる言葉でプロダクトを命名する。
- Subheading（サブ見出し） ：誰がどんなベネフィットを得られるかを1行で記述する。
- Summary（サマリ）：プロダクトとベネフィットを簡潔に記述する。
- Problem（課題）：プロダクトが解決する問題を記述する。
- Solution（ソリューション）：プロダクトがどうやって鮮やかに課題を解決するかを記述する。
- Quote from You（提供側の声）：プロダクトを提供している側からの声を記述する。
- How to Get Started（始め方）：使い始めるのが簡単であることを記述する。
- Quote from Customer（顧客の声）：顧客（仮）がどうベネフィットがあったかを記述する。
- Closing and Call to Action（クロージングと行動の呼びかけ）：まとめと、読み手に次にすべきステップを記述する。
そのフォーマット
まとめ: 開発者が考える提案書 補講 - Amazon流Internal Press Releaseテンプレート - Qiita
c.f. Design Docs at Google
【翻訳】Googleのエンジニアがソフトウェア開発する時に必ず書くドキュメント「Design Docs at Google」 - BppLOG
基本的なドキュメントの書き方
最後に基本的なツール群です。
質の高い技術文書を書く方法
Google社のテクニカルライティングの基礎教育資料がとても良かったので紹介したい
ドキュメント作成スキル向上を目指す人向けおすすめ記事まとめ
エンジニア歴20数年の私が、設計書を書く際に心がけていること
Markdown記法 チートシート
スライド化
爆速でスライドを作る！Markdownからスライドを作れる「Marp」
お洒落は最低限これでよし。
Sample
こんな感じになりました
参考資料
以下資料をベースにしています。エンジニアだからこそ知っていることを活かして意見を言って欲しい、提案して欲しい、そう周りから言ってもらえる状況は開発者として有り難いですよね。テンプレートが参考になればさいわいです。
良い提案書を書く方法（システム開発）
エンジニア提案をしよう
指示をするなら”得たい結果”を指示する
テンプレート: 外資ITトップセールスが考えた提案書テンプレートを配布します!!
プロダクト企画にエンジニアを巻き込む ... こちらは巻き込む目線の記事。