簡単な手順書を書いてみよう

ストーリー

「手順書の読み方はわかったね。次は自分で書いてみよう」

「いきなり書けるか不安です...」

「最初は簡単な手順から始めよう。日常的にやっている作業を、誰かに教えるつもりで書いてみて」

手順書を書く基本ステップ

Step 1: 作業を実際にやりながらメモを取る

実行するコマンド・操作:
1. git pull origin main
2. npm install
3. npm run dev
4. ブラウザで localhost:3000 を開く

確認した結果:
- git pull: Already up to date.
- npm install: added 0 packages
- npm run dev: Server started on port 3000
- ブラウザ: トップページが表示された

Step 2: メモを手順書の形式に整える

# 開発環境起動手順書

## 概要
ローカル開発環境を起動するための手順です。

## 前提条件
- Node.js 18以上がインストールされていること
- プロジェクトがクローン済みであること

## 手順

### 1. 最新のコードを取得する
```bash
git pull origin main

【確認】以下のようなメッセージが表示される

Already up to date.

または変更があった場合はファイル一覧が表示される

2. 依存パッケージをインストールする

npm install

【確認】エラーなく完了する

3. 開発サーバーを起動する

npm run dev

【確認】以下のメッセージが表示される

Server started on port 3000

4. ブラウザで動作確認する

ブラウザで http://localhost:3000 を開く

【確認】トップページが正常に表示される

完了確認

• 開発サーバーが起動している
• ブラウザでページが表示される

### Step 3: 他の人にレビューしてもらう

書いた手順書を他の人に見てもらい、フィードバックをもらいます。

確認ポイント:

• 前提条件は十分か？
• 手順は具体的か？
• 確認ポイントは適切か？
• 不足している情報はないか？

---

## 手順書テンプレート

以下のテンプレートを使って手順書を書きましょう。

```markdown
# [作業名] 手順書

## 概要
[この手順書で何ができるようになるか、1-2文で説明]

## 前提条件
- [条件1]
- [条件2]
- [条件3]

## 作業時間の目安
約[X]分

## 手順

### 1. [ステップのタイトル]
[説明文]

```bash
[実行するコマンド]

【確認】[期待される結果]

2. [ステップのタイトル]

[説明文]

[操作手順や設定内容]

【確認】[期待される結果]

3. [ステップのタイトル]

...

完了確認

• [確認項目1]
• [確認項目2]
• [確認項目3]

トラブルシューティング

[エラーメッセージや症状]

原因: [原因の説明] 対処: [対処方法]

関連ドキュメント

• [関連する手順書やドキュメントへのリンク]

---

## 手順書を書くときのコツ

### 1. 「初めての人」を想像して書く

NG: 「いつもの設定をする」 （書いた本人にしかわからない）

OK: 「config.json を開き、"environment" の値を "development" に変更する」 （誰でも同じ操作ができる）

### 2. スクリーンショットを活用する

GUI操作が含まれる場合は、スクリーンショットが有効です。

```markdown
### 3. AWSコンソールでインスタンスを起動する

1. EC2ダッシュボードを開く
2. 「インスタンスを起動」をクリック

![インスタンス起動ボタン](./images/ec2-launch-button.png)

3. インスタンス名を入力
...

3. 「なぜ」も書く（必要に応じて）

### 2. キャッシュをクリアする

```bash
npm cache clean --force

なぜ必要？: 古いキャッシュが原因で依存関係のエラーが発生することがあるため

### 4. コマンドの出力例を示す

```markdown
### 3. バージョンを確認する

```bash
node --version

出力例:

v18.17.0

※ バージョンは v18.0.0 以上であること

### 5. 危険な操作には警告を入れる

```markdown
### 5. データベースをリセットする

> ⚠️ **警告**: この操作ですべてのデータが削除されます。本番環境では絶対に実行しないでください。

```bash
npm run db:reset

---

## よくある失敗と改善

### 失敗1: 手順が抽象的すぎる

```markdown
❌ 悪い例:
1. 設定を変更する
2. サーバーを再起動する

✅ 良い例:
1. /etc/nginx/nginx.conf を開き、worker_processes を 4 に変更する
2. sudo systemctl restart nginx を実行する

失敗2: 確認ポイントがない

❌ 悪い例:
1. npm install を実行する
2. npm run build を実行する

✅ 良い例:
1. npm install を実行する
   【確認】"added X packages" と表示され、エラーがないこと

2. npm run build を実行する
   【確認】"Build completed successfully" と表示されること

失敗3: 前提条件が不明確

❌ 悪い例:
## 前提条件
- 環境が整っていること

✅ 良い例:
## 前提条件
- Node.js 18.0.0 以上がインストールされていること（確認: node --version）
- npm 9.0.0 以上がインストールされていること（確認: npm --version）
- プロジェクトが ~/projects/myapp にクローン済みであること

練習: 日常作業を手順書にしてみよう

以下のような日常作業を手順書にしてみましょう。

まとめ

チェックリスト

• 手順書を書く3つのステップを理解した
• テンプレートの構成要素を理解した
• よくある失敗パターンと改善方法を理解した

次のステップへ

手順書の書き方の基本は理解できましたか？

次のセクションでは、プロジェクトの入り口となる「README」の書き方を学びます。 READMEは手順書とは少し違う目的を持つ重要なドキュメントです。

推定読了時間: 30分