はじめに

こんにちは！IT企業で働く2年目のエンジニアです。

2年目になって、こんなドキュメントを書く機会が増えました：

データベース移行の手順書
API調査レポート
システム構築マニュアル

最初は「どう書けばいいんだろう...」と悩みましたが、1年間の試行錯誤で、良いドキュメントを作るコツが分かってきました。

この記事では、実務で学んだ5つのポイントを、実例付きでお伝えします！

こんな人におすすめ

✅ ドキュメント作成に苦手意識がある
✅ 何を書けばいいか分からない
✅ 自分の書いたドキュメントが分かりにくいと言われる
✅ もっと良いドキュメントを書きたい

1. 最初に「誰のため」「何のため」を書く

なぜ大事？

ドキュメントを開いて最初に思うこと：

「これ、私が読むべき？」
「読んだら何が分かるの？」

この疑問に答えないと、読み手は迷子になります。

必ず書く4つの情報

項目	内容
🎯 目的	このドキュメントで何ができるようになるか
👥 対象読者	誰が読むことを想定しているか
📚 前提知識	必要なスキルレベル
📍 範囲	カバーする/しない内容

実例：データベース移行手順書の場合

❌ 悪い例（情報が足りない）

# データベース移行手順

以下の手順でデータベースを移行してください。

✅ 良い例（必要な情報が揃っている）

# データベース移行手順書

## 📝 この手順書について

**目的**  
動画レコメンドシステムのデータベースを新環境に移行する

**誰が読む？**  
- リリース作業を実施する運用担当者
- 作業を承認するチームリーダー

**必要な知識**  
- Linuxの基本コマンド（cd, cp, lsなど）
- Tomcatサーバーへのログイン方法
- データベース接続の基礎知識

**この手順書でカバーする範囲**  
✅ 商用環境の移行手順  
❌ ラボ環境（別手順書を参照）

これだけで変わること

読み手は5秒で判断できます：

✅ 自分が読むべきドキュメントか
✅ 読んだら何が得られるか
✅ 自分に必要な知識があるか

2. 結論を最初に、構造は階段式に

なぜ大事？

エンジニアは忙しい！
全部読む時間がない人も多いです。

だから：

最初に結論を書く
詳細は後で書く
見出しで構造化する

基本の型：逆三角形

━━━━━━━━━━━━━━━━━
  結論・要約（全員が読む）
━━━━━━━━━━━━━━
   詳細説明（必要な人が読む）
━━━━━━━━━━
    補足情報（興味ある人が読む）
━━━━━

実例：API調査レポートの場合

❌ 悪い例（結論が最後）

# MoBills API調査

## API仕様
MoBills APIはREST形式で...
（長い説明が続く）

## 認証方式
OAuth 2.0を使用しており...
（また長い説明）

## 調査結果
連携可能です。ただし課題が2つあります。

👎 結論が最後まで分からない

✅ 良い例（結論が最初）

# MoBills API調査結果

## 🎯 結論（3行まとめ）

**連携できます！** ただし以下の対応が必要：
1. 認証トークンの自動更新機能を追加
2. エラー時のリトライ処理を実装

## 📋 詳細

### 使えるAPI
- 月額課金の登録・解除
- 決済履歴の照会
- ユーザー情報の管理

### 必要な作業
（詳しい説明）

## 📚 参考：技術仕様
（さらに詳しい情報）

👍 3秒で結論が分かる

見出しの付け方のコツ

見出しだけ読んで内容が分かるように：

❌ 悪い見出し

「概要」
「詳細」
「その他」

✅ 良い見出し

「連携可能。ただし2つの課題あり」
「認証トークンは24時間で期限切れ」
「エラー時は自動リトライが必要」

使える記号で見やすく

記号	使い方
🎯	目的・結論
✅	できること
❌	できないこと
⚠️	注意事項
💡	ポイント・ヒント
📝	手順・やること

3. 手順は「コピペでできる」レベルで書く

なぜ大事？

曖昧な手順 = 事故のもと

手順書で一番大事なこと：

誰がやっても、同じ結果になる

やってはいけない書き方

❌ 悪い例	✅ 良い例
設定ファイルを編集	`/opt/tomcat/conf/server.xml` を編集
サーバーにログイン	`ssh tomcat@192.168.x.x` でログイン
適切な値を設定	`max_connections=100` に設定
しばらく待つ	30秒待つ

手順書に必ず書く3つ

具体的なコマンド（コピペできる）
期待される結果（正しくできたか確認）
所要時間（作業計画が立てられる）

実例：Tomcat再起動手順

❌ 悪い例

1. Tomcatを停止する
2. バックアップを取る
3. ファイルを配置する
4. Tomcatを起動する
5. 確認する

👎 これでは作業できない

✅ 良い例

## Tomcat再起動手順

**作業サーバー：** your-server-name (<サーバーIP>)  
**作業ユーザー：** tomcat  
**作業時間：** 約15分

### 手順1: サーバーにログイン（1分）

```bash
# あなたのPCから実行
ssh tomcat@<サーバーIP>

確認： プロンプトが [tomcat@your-server ~]$ になる

手順2: Tomcatを停止（2分）

# Tomcatの停止
/opt/tomcat/bin/shutdown.sh

# 停止を確認（何も表示されなければOK）
ps -ef | grep tomcat

確認： Tomcatのプロセスが表示されない

⚠️ 注意： もしプロセスが残っていたら、先輩に相談

手順3: バックアップ作成（1分）

# 既存ファイルをバックアップ
cd /opt/tomcat/webapps
cp myapp.war myapp.war.backup_$(date +%Y%m%d_%H%M%S)

# 確認
ls -lh myapp.war*

確認： 日時付きのバックアップファイルができている
例: myapp.war.backup_20250115_140530

手順4: 新ファイル配置（1分）

# 新しいファイルを配置
cp /tmp/myapp.war /opt/tomcat/webapps/

# ファイルの確認
ls -lh /opt/tomcat/webapps/myapp.war

確認： ファイルサイズが新しくなっている

手順5: Tomcat起動（5分）

# Tomcat起動
/opt/tomcat/bin/startup.sh

# 起動完了を待つ（30秒〜1分）
sleep 60

# 起動完了メッセージを確認
tail -n 50 /opt/tomcat/logs/catalina.out | grep "Server startup"

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

Server startup in [12345] milliseconds

⏱️ 待ち時間： 30秒〜1分ほどかかります

💡 リアルタイムでログを見たい場合:

tail -f /opt/tomcat/logs/catalina.out
# 「Server startup in...」が表示されたらCtrl+Cで終了

手順6: 動作確認（5分）

ブラウザで以下のURLを開く：

https://your-system.example.com/myapp/health

確認： 画面に {"status": "OK"} と表示される

✅ 成功！ 作業完了です


### 手順書を書くときのチェックリスト

書き終わったら、以下を確認：

- [ ] コマンドがコピペできる形式になっている
- [ ] サーバー名、IPアドレスが具体的
- [ ] ファイルパスが正確
- [ ] 各手順の確認方法が書いてある
- [ ] 所要時間の目安がある
- [ ] エラー時の対処法がある

## 4. 「なぜ」を書くと、応用が効く

### なぜ大事？

手順だけ書いても：
- トラブル時に対応できない
- 応用が効かない
- 怖くて実行できない

**「なぜ」を書くメリット：**
- 理解が深まる
- イレギュラー対応ができる
- 安心して作業できる

### 「なぜ」を書く3つの場面

#### 1️⃣ 作業の背景を説明

**例：データベース接続方式の変更**

```markdown
## なぜこの作業をするのか

### 背景
現在のシステムはOCI接続でデータベースに繋いでいます。
でも、新しいサーバーではOracleクライアントが使えません。

### OCI接続とThin接続の違い

| 項目 | OCI接続 | Thin接続 |
|------|---------|----------|
| 必要なもの | Oracleクライアント | 不要（Javaだけ） |
| 特徴 | ネイティブで高速 | Java実装（通常は十分な速度） |
| 設定 | 簡単 | 少し複雑 |

### 今回の選択
新サーバーではOracleクライアントがインストールできないため、
**Thin接続に変更します。**

💡 **ポイント：** セキュリティポリシーの制約です

2️⃣ 前提条件を明確に

作業前のチェックリスト形式がおすすめ：

## ⚠️ 作業前に必ず確認すること

### システムの状態
- [ ] 新データベースが起動している
- [ ] ネットワークが繋がる（pingが通る）
- [ ] テーブルとデータが準備済み

### 権限の確認
- [ ] サーバーにログインできる
- [ ] sudoコマンドが使える
- [ ] ファイルの読み書きができる

### タイミング
- [ ] メンテナンス時間帯（深夜2時〜3時）
- [ ] チームリーダーの承認済み
- [ ] 関係者に通知済み

### バックアップ
- [ ] データベースのバックアップ済み
- [ ] 設定ファイルのバックアップ済み
- [ ] ロールバック手順を確認済み

3️⃣ 影響範囲を伝える

誰が困るか、いつ困るかを明確に：

## 🚨 この作業の影響範囲

### 止まるシステム
- 動画レコメンド機能
- お気に入り機能
- 視聴履歴

### 影響を受ける人
- **ユーザー：** 約10万人（全員）
- **管理者：** 5名

### システム停止時間
- **予定：** 15分
- **最大：** 30分（問題発生時）

### 停止する時間帯
📅 **2025年1月15日（水） 2:00 - 2:30**

💡 この時間はアクセスが少ない深夜です

### もし失敗したら？
バックアップから復旧します（所要時間の目安：10〜20分）  
ロールバック手順は[こちら](./rollback.md)を参照

実例：なぜを書いた手順書

## Step 3: workディレクトリを削除

### なぜこの作業が必要？
Tomcatは起動時にJSPファイルをコンパイルして、
workディレクトリにキャッシュします。

古いキャッシュが残っていると：
❌ 古いコードが実行される  
❌ 画面が真っ白になる  
❌ エラーが出る

だから、**新しくデプロイする前にキャッシュを削除**します。

### 削除コマンド
```bash
rm -rf /opt/tomcat/work/Catalina/localhost/myapp

なぜ `-rf` オプション？

-r: ディレクトリごと削除
-f: 確認なしで削除

⚠️ 注意： パスを間違えないように！


### 「なぜ」を書くときのコツ

1. **専門用語は説明する**
   - OCI接続 → Oracleクライアントが必要な接続方式
   - JSPコンパイル → JSPファイルをJavaに変換すること

2. **図や表を使う**
   - 比較表で違いを分かりやすく
   - チェックリストで漏れを防ぐ

3. **具体的な数字を出す**
   - 「多くのユーザー」→「約10万人」
   - 「すぐ」→「30秒」
   - 「しばらく」→「1〜2分」

## 5. 後から探せる、更新できる仕組み

### なぜ大事？

ドキュメントは**生き物**です：
- 情報は古くなる
- 新しい問題が見つかる
- 他の人が更新する

**だから、メンテナンスしやすく作る必要があります。**

### 5-1. 探しやすさ：検索でヒットする工夫

#### エラーメッセージを具体的に書く

❌ 悪い例
```markdown
データベース接続エラーが出ます

✅ 良い例

### エラー: ORA-12505 Listener refused the connection

**エラーメッセージ（そのまま）:**

java.sql.SQLException: Listener refused the connection
ORA-12505, TNS:listener does not currently know of SID

💡 ポイント： エラーメッセージをそのまま書くと、検索でヒットする

関連ドキュメントをリンクする

## 📚 関連情報

**この手順に関連するドキュメント：**
- [データベース移行計画書](./db_migration_plan.md)
- [アプリケーション仕様書](./app_spec.md)
- [Tomcat運用マニュアル](./tomcat_ops.md)

**困ったときに見るドキュメント：**
- [トラブルシューティングガイド](./troubleshooting.md)
- [障害発生時の連絡先](./emergency_contact.md)

5-2. 更新しやすさ：履歴を残す

ドキュメントの管理情報

ファイルの先頭に書く：

# データベース移行手順書 v2.1

| 📋 項目 | 内容 |
|---------|------|
| 作成日 | 2024-12-01 |
| 最終更新 | 2025-01-10 |
| 作成者 | 中田 |
| 確認者 | 水上チームリーダー |
| 次回見直し | 2025-07-01 |
| バージョン | 2.1 |

---

更新履歴を表で管理

## 📝 更新履歴

| 日付 | Ver | 更新者 | 何を変えた？ |
|------|-----|--------|-------------|
| 2024-12-01 | 1.0 | 中田 | 初版作成 |
| 2024-12-15 | 1.1 | 中田 | ラボ環境で検証した結果を追加 |
| 2025-01-05 | 2.0 | 中田 | ロールバック手順を追加 |
| 2025-01-10 | 2.1 | 中田 | レビュー指摘を反映（環境情報を具体的に） |

💡 ポイント： 「何を変えたか」を具体的に書く

さいごに

この記事が、技術ドキュメント作成で悩んでいる方の助けになれば嬉しいです。

「こんな工夫もあるよ！」というアイデアがあれば、
ぜひコメントで教えてください！

最後まで読んでいただき、ありがとうございました！