上流工程側ドキュメント作成メモ【自分用備忘録】

自分用メモです。

## フローチャート作成の基本ルール

### 1. **基本ルールを統一する**  
- **図形の意味を統一させる**
（例: 処理＝長方形、判断＝ひし形、開始/終了＝楕円）  
-  __矢印の向きは一方向（通常上から下、左から右）__ にそろえる  
- **同じサイズ感・間隔を意識する**  

:::note info
パワポの場合は、1ページの情報量が多くならないようにしましょう。
- 1Pに強調したいことは1つまで
- フローチャートは2行まで
- 「資料」というより「画像」のような感覚で作成してみる
:::


### 2. **シンプルな構造を心がける**  
- 無駄な詳細は省き、**「誰が見てもすぐ理解できる」** 流れにする  
- 複雑になりすぎる場合は**サブフローに分ける**  
⇒ ページを分けちゃって大丈夫です。

### 3. **適切なレベルでの抽象化**  
- 重要な処理を**大きなブロック単位**でまとめ、細かい部分は別図や注釈に分ける  
- **例:**  
  - 高レベル → 大まかな処理の流れ（クラス図、シーケンス図、入出力）
  - 低レベル → 実装に近い詳細な手順（上記+ 処理フローチャート、E-R図等）

:::note info
後の章でも触れますが、説明する相手によってどこまで分解させるか調整します。
実装をお願いする場合、もちろん詳細設計レベルの資料が必要になります。
:::


### 4. **見やすいレイアウトを意識**  
- 縦の流れを中心に、できるだけ横幅を広げすぎない  
- 処理が分岐する際には、十分な間隔を取る  
- 色やアイコンを適度に使い、視認性を向上させる  

:::note info
色分け、アイコンは視認性向上に効果的ですが、使いすぎると逆効果になります。

一例として
 __太字部分は「本当に強調したい箇所だけ」
赤字は「本当に目を引かせたい箇所だけ」
注釈は、背景を薄ピンクにしておく。
フォントは基本メイリオ。見出し1のフォントサイズは32pixel。見出し2は...__ 
のように、あらかじめ自分用ルールを決めて資料作成するとスムーズです。

色は多くても3色、できれば2色以内にしましょう。

※ 会社でフォーマットが決まっていたらもちろんそれに従いましょう。
:::


---

## 仕様書作成の基本ルール  

### 1. **目的と対象読者を明確にする**  
- 仕様書を読む人（開発者、運用担当者、非エンジニア）に合わせた表現を使う
例：技術者向け→技術的詳細を、マネージャー向け→概要と要点を重視  

### 2. **構成を整える（見出しの一貫性）**  
業界によって変わってきそうですが、標準的な構成例としては
1. **概要（目的・背景）**  
2. **システムの全体像（構成図やフロー図）**  
3. **詳細仕様（機能・入出力・制約）**  
4. **インターフェース（API、データ形式）**  
5. **エラーハンドリング**  
6. **運用・保守情報**  

と思います。

構成に迷ったら、上司や先輩の作成したドキュメントを盗み見して真似しちゃっていいと思います。

### 3. **表や図を活用して視覚的に分かりやすく**  
- テキストだけでなく、**表・図・リスト** を活用して可読性を高める 
⇒ 簡単なお絵描き（ポンチ図など）があると尚Good
 **例:** データの入出力仕様 → 表形式、システムフロー → 図示  

### 4. **具体的な例やサンプルを記載**  
- 理解を助けるために、実際のデータ例を示す  
- 「処理の流れがわかるシナリオ」を挿入することで、より直感的に理解させる  

:::note info
実際の売り上げのデータ等、現実を突きつけるような資料だと説得力も増します。
 __数字と流れ（シナリオ）__ は基本的にはどんな場面でも強力な武器になります。
:::


### 5. **適切なフォーマット・テンプレートを使用**  
- チーム内で仕様書の**テンプレート**を統一する  
例：Markdown、Excel、Word など、相手が扱いやすい形式にする  

:::note info
取引先が何のソフトを使っているかを、取引序盤にしれっと聞いておくと後々楽です。
:::


### 6. **可読性の高い文章を書く**  
- 長い文は避け、**箇条書き**を活用する（特にパワポ）
- 専門用語には補足説明をつける（Note: とか 補足: とかつけて）
- 主語・述語を明確にし、一文を短くする  

---

## **フローチャート・仕様書の共通ポイント**  

1. **レビューの機会を設ける**  
    他の人に読んでもらい、**「分かりにくい点」をフィードバックしてもらう**  

2. **変更履歴を明確にする**  
   いつ、誰が、何を修正したかを記録しておくことで管理しやすくなる  

3. **一貫性を保つ**  
   用語、フォーマット、命名規則などを統一することで、長期的に管理しやすくなる  

:::note info
しごでき上司に作成した資料を実際に見てもらって
耳の痛いフィードバックを受けながら修正していく作業が一番上達すると思います（個人的な体験談）
:::

## おまけ：ドキュメントの役割とゴール

### **1. 各ドキュメントの違い**
実装前に必要になるのは主に以下の3つのドキュメントです。
システム開発の流れに沿って作成されます。
（典型的なウォーターフォール型開発を想定します）

### **① 要件定義書**（何を作るかを決める）  
- **目的**：**「顧客の要求」** を整理・具現化・細分化し、システムが実現すべき機能や性能を明確にする  
- **作成者**：主に**システムエンジニア（SE）**  
- **読者**：顧客（ビジネス側）・開発者  
- **内容の例**：
  - システムの目的・背景
  - 実装する機能（業務フロー）
  - 要求される性能（応答時間、処理能力）
  - ユーザー要件（操作方法、UIの簡単さ）
  - 制約（対応OS、使用する技術）

 **例：「ECサイトを作る」 → 「ユーザーが商品をカートに入れられるようにする」**  

 :::note info
 __要求する側も何が欲しいのかよくわかっていないことがあります。__ 
実現できるかどうかはまずは置いておき、しっかり深堀りして、相手の話を「正確に」聞くフェーズです。

できればさっと簡易的なUIや機能を提示して、「そうそうそんな感じ」と返答を貰えたら後が楽です。
:::


---

### **② 設計書（基本設計・詳細設計）**（どのように作るかを決める）  
- **目的**：要件定義書をもとに、システムの設計を行う  
- **作成者**：**システムエンジニア（SE）、プログラマー**  
- **読者**：開発者・テスター  
- **種類**：
  1. **基本設計書**（外部設計）→ システムの大枠を設計  
     - 画面設計（UI設計）  
     - データベース設計（ER図）  
     - 処理フロー（業務フロー、シーケンス図）  
  2. **詳細設計書**（内部設計）→ コードに落とし込むための細かい設計  
     - 関数・APIの仕様  
     - クラス設計（オブジェクト指向の場合）  
     - テーブル構成（データ型・制約条件など）  

**例：「カート機能を実装する」 → 「ボタン押下でカートに商品IDを保存するSQLを実行する」**  

:::note info
要件定義のヒアリングでそれだけ要求を具現化できたかで、ここのフェーズがスムーズになるか否かが決まります。

また、制約（自分のチームメンバでどこまでできるか）については早めに見極めた方がいいです。
:::


---

### **③ 仕様書**（どのように動作するかをまとめる）  
- **目的**：**「システムがどのように動作するか」** を開発者・運用者に伝える  
- **作成者**：開発者・テスター・運用担当者  
- **読者**：開発者・保守担当者  
- **内容の例**：
  - システムの動作仕様（API仕様、エラーハンドリング）  
  - 画面遷移図  
  - パラメータやデータの入出力定義  

 **例：「カートの最大商品数は99個まで」など、動作ルールを記載**  

---

## **2. フローチャートの位置づけ**
 **（基本的に）フローチャートは「設計書（基本設計）」の中に属します。**
 
フローチャートは「処理の流れを視覚化」 するものなので、多くの場合 **「基本設計書」** の一部として作成されます。  

 __設計書に含まれる図の例__ 
- **業務フロー図（ビジネスプロセスの流れ）** → 要件定義書にも含まれることがある  
- **フローチャート（アルゴリズムの流れ）** → 基本設計書  
- **シーケンス図（システムの処理順序）** → 基本設計書  
- **クラス図（オブジェクト指向の設計）** → 詳細設計書   

:::note info
個人的なお勧めですが、 __どの段階でも簡単なリストや業務フロー図を作成しておくと理解の手助けになります。__ 
プチマニュアルとも言い換えることもできます。

例えば「この工程ではAさんに伝えて、Cさんに承認とって...」みたいなのを __文章ではなくフロー図やリストでまとめておくと、関わる人や報告頻度が増える繁忙期でビジブルに再確認でき、作っておいて良かったとなるはずです。__ 

:::


---

## **3. まとめ**
| ドキュメント名 | 目的 | 誰向け？ | 例 |
|----|----|----|----|
| **要件定義書** | 何を作るか（顧客の要求） | ビジネス側・開発者 | 「ユーザーがカートに商品を入れられる」 |
| **設計書（基本設計・詳細設計）** | どう作るか（システムの設計） | 開発者 | 「カートボタン押下でDBに商品IDを保存」 |
| **仕様書** | どのように動作するか（システムの詳細） | 開発者・運用者 | 「カートの最大商品数は99個まで」 |
| **フローチャート** | 処理の流れを視覚化 | 設計書（基本設計）の一部 | 「購入ボタン→在庫確認→決済処理」 |

:::note warn
 **「仕様書」** という言葉は広義で使われることもあり、設計書や要件定義書を含めて指すこともあります。
依頼内容の担当範囲を聴いて「？？？」ってなったら絶対再確認した方がいいです。

:::


---

## **4. フローチャートと他の図の関係**
- **要件定義書 → 業務フロー図（業務の流れ）**  
- **基本設計書 → フローチャート（処理の流れ）・シーケンス図**  
- **詳細設計書 → クラス図・テーブル設計**  



 「今回の仕事にフローチャートいる？」と悩んだら？
 
⇒「設計の一部として説明が必要か？」で判断するといいです。  
 **開発者向けの設計書ならぶち込んでOK**、**運用向けの仕様書なら不要なことが多い** です。  

おわり