技術文書の種類
ストーリー
「ドキュメントが大事なのは分かったけど、どんな種類があるの？」
「いろいろあるよ。議事録、日報、手順書、設計書...」
「え、そんなにあるんですか？」
「大丈夫。まずは種類と用途を整理しよう。全部いっぺんに覚える必要はないから」
技術文書の全体像
IT業界で使われる主な技術文書を、頻度別に整理しました。
日常的に書く文書
| 種類 | 目的 | 頻度 |
|---|---|---|
| 議事録 | 会議の決定事項とアクションを記録 | 会議のたびに |
| 日報/週報 | 作業の進捗を報告 | 毎日/毎週 |
| チャットでの技術説明 | 簡潔に技術的内容を伝える | 毎日 |
プロジェクトで書く文書
| 種類 | 目的 | 頻度 |
|---|---|---|
| 手順書 | 作業手順を誰でも再現できるように | 新しい作業のたびに |
| README | プロジェクトの概要と使い方を説明 | プロジェクトごとに |
| 設計書 | システムの構造や設計を説明 | 開発フェーズで |
| API仕様書 | APIの使い方を説明 | API開発時に |
特別な場面で書く文書
| 種類 | 目的 | 頻度 |
|---|---|---|
| 障害報告書 | 障害の原因と対応を記録 | 障害発生時 |
| リリースノート | 変更内容をユーザーに伝える | リリース時 |
| 技術ブログ | 技術知見を 社内外に共有 | 任意 |
各文書の詳細
1. 議事録
目的: 会議で決まったことを記録する
markdown
# 定例ミーティング 議事録
日時: 2025-04-01 10:00-11:00
参加者: 田中、佐藤、鈴木
## アジェンダ
1. 先週の進捗確認
2. 新機能の仕様決定
## 決定事項
- ログイン機能はOAuth2.0を採用する
- リリース日は4月15日とする
## アクションアイテム
- [ ] 田中: OAuth2.0の実装（4/7まで）
- [ ] 佐藤: テストケース作成（4/10まで）このミッションのStep 2で詳しく学びます。
2. 日報/週報
目的: 自 分の作業内容と進捗をチームに共有する
markdown
# 週報 2025-04-01 〜 04-05
## 今週の成果
- ログイン画面のUI実装完了
- 単体テスト10件作成
## 来週の計画
- API連携の実装
- 結合テスト開始
## 課題・リスク
- API仕様書が未確定（佐藤さんに確認中）
## 学んだこと
- React Hooksの使い方が分かったこのミッションのStep 3で詳しく学びます。
3. 手順書
目的: 誰がやっても同じ結果になるように手順を記録する
markdown
# 開発環境セットアップ手順
## 前提条件
- macOS 12以降 または Windows 10以降
- Node.js v18以降がインストール済み
## 手順
### 1. リポジトリをクローン
git clone https://github.com/example/project.git
### 2. 依存パッケージをインストール
cd project
npm install
### 3. 環境変数を設定
cp .env.example .env
# .envファイルを編集し、必要な値を設定
### 4. 開発サーバーを起動
npm run dev
## 確認ポイント
- ブラウザで http://localhost:3000 にアクセスできることこのミッションのStep 4で詳しく学びます。
4. README
目的: プロジェクトの概要と使い方を最初に伝える
READMEはプロジェクトの「顔」です。GitHubでリポジトリを開いたときに最初に表示されます。
このミッションのStep 4で詳しく学びます。
5. 障害報告書
目的: 障害の原因、影響、対応、再発防止策を記録する
markdown
# 障害報告書
## 概要
- 発生日時: 2025-04-01 14:30 〜 15:00
- 影響範囲: 全ユーザーのログイン機能
- 重要度: Critical
## 原因
認証サーバーの証明書が期限切れとなり、
SSL接続に失敗していた。
## 対応
証明書を更新し、サービスを再起動した。
## 再発防止策
- 証明書の有効期限を監視するアラートを設定
- 自動更新の仕組みを導入このミッションのStep 3で詳しく学びます。
6. 設計書・API仕様書
これらは中級者以上のスキルが必要です。 このミッションでは紹介のみとし、L1以降で詳しく学びます。
| 文書 | 内容 |
|---|---|
| 設計書 | システムの構造、データの流れ、技術選定の理由 |
| API仕様書 | エンドポイント、リクエスト/レスポンスの形式 |
L0で書けるようになるべき文書
このミッションでは、以下の文書を書けるようになることを目指します。
優先度: 高 優先度: 中
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 議事録 │ │ 週報 │ │ 手順書 │
│ │ │ │ │ │
│ Step 2で学習 │ │ Step 3で学習 │ │ Step 4で学習 │
└─────────────┘ └─────────────┘ └─────────────┘
まとめ
| ポイント | 内容 |
|---|---|
| 日常文書 | 議事録、日報/週報 |
| プロジェクト文書 | 手順書、README、設計書 |
| 特別文書 | 障害報告書、リリースノート |
| L0の目標 | 議事録・週報・手順書・READMEが書ける |
- 技術文書の種類を把握した
- 各文書の目的を理解した
- L0で目指すレベルを確認した
次のステップへ
技術文書の全体像が見えましたか？
次のセクションでは、これらの文書を書くときに使う「Markdown」という記法を学びます。 Markdownを覚えれば、どの文書もきれいに書けるようになります。
推定読了時間: 25分