1 / 22

📖

Part 07 Unit 02

實戰專案：技術文件產生器

用 AI 快速生成專業技術文件

API 文件、使用手冊、安裝指南

2 / 22

專案目標

建立技術文件自動化系統：

標準化的文件模板
AI 輔助內容生成
多格式輸出（HTML、PDF、Word）
自動生成目錄和索引

3 / 22

技術文件類型

類型	內容	讀者
API 文件	端點、參數、回應	開發者
使用手冊	功能說明、操作步驟	使用者
安裝指南	環境需求、安裝步驟	管理員
開發文件	架構、程式碼說明	開發團隊

4 / 22

步驟 1：建立專案結構

mkdir D:\TechDocs
cd D:\TechDocs
mkdir src        # 原始 Markdown
mkdir templates  # 模板
mkdir output     # 輸出目錄
mkdir assets     # 圖片資源

📁 TechDocs/ ├── 📁 src/ ├── 📁 templates/ ├── 📁 output/ └── 📁 assets/

5 / 22

步驟 2：API 文件模板

---
title: API 文件
version: 1.0.0
date: 2025-01-01
---

# API 名稱

## 概述
簡短描述 API 的用途和功能。

## 基本資訊
- **Base URL**: `https://api.example.com/v1`
- **認證方式**: Bearer Token

## 端點

### GET /endpoint
**描述**：取得資源

**參數**：
| 名稱 | 類型 | 必填 | 說明 |
|------|------|------|------|
| id | string | 是 | 資源 ID |

**回應範例**：
```json
{
  "status": "success",
  "data": {}
}
```

## 錯誤碼
| 代碼 | 說明 |
|------|------|
| 400 | 請求格式錯誤 |
| 401 | 未授權 |

6 / 22

步驟 3：使用 AI 生成內容

請根據以下程式碼，生成 API 文件：

程式碼：
[貼上 API 程式碼]

要求：
1. 使用 Markdown 格式
2. 包含：概述、端點列表、參數說明、回應範例
3. 每個端點需要：HTTP 方法、路徑、描述、參數表格、回應範例
4. 加入錯誤碼說明
5. 加入認證說明

7 / 22

步驟 4：使用手冊模板

---
title: 使用手冊
product: 產品名稱
version: 1.0
---

# 產品名稱 使用手冊

## 快速開始
3 分鐘內開始使用本產品。

### 步驟 1：安裝
...

### 步驟 2：設定
...

### 步驟 3：第一次使用
...

## 功能說明

### 功能 A
**用途**：...
**操作步驟**：
1. ...
2. ...

## 常見問題

### Q: 問題描述？
A: 解答...

## 聯絡支援
- Email: support@example.com

8 / 22

步驟 5：AI 生成使用手冊

請為以下產品功能撰寫使用手冊：

產品：[產品名稱]
功能：[功能列表]

要求：
1. 使用簡單易懂的語言
2. 每個功能包含：用途說明、操作步驟（有編號）、注意事項
3. 加入「快速開始」章節
4. 加入「常見問題」章節
5. 使用 Markdown 格式，適當使用圖片佔位符 ![描述](path)

9 / 22

步驟 6：建立文件轉換腳本

# build-docs.ps1
# 技術文件建置腳本

param(
    [string]$Format = "all"  # html, pdf, docx, all
)

$srcFiles = Get-ChildItem src\*.md
$css = "templates\tech-style.css"
$template = "templates\tech-template.html"

foreach ($file in $srcFiles) {
    $base = $file.BaseName
    Write-Host "📄 處理: $($file.Name)" -ForegroundColor Cyan

    if ($Format -eq "html" -or $Format -eq "all") {
        pandoc $file.FullName -o "output\$base.html" `
            --standalone --toc --css=$css --template=$template
        Write-Host "  ✅ HTML" -ForegroundColor Green
    }

    if ($Format -eq "docx" -or $Format -eq "all") {
        pandoc $file.FullName -o "output\$base.docx" `
            --toc --reference-doc=templates\tech-reference.docx
        Write-Host "  ✅ DOCX" -ForegroundColor Green
    }
}

Write-Host "`n✅ 建置完成！" -ForegroundColor Green

10 / 22

步驟 7：專業 HTML 樣式

/* tech-style.css */
body {
    font-family: -apple-system, 'Microsoft JhengHei', sans-serif;
    max-width: 900px;
    margin: 0 auto;
    padding: 40px;
    line-height: 1.7;
}
h1 { color: #2c3e50; border-bottom: 3px solid #3498db; }
h2 { color: #34495e; margin-top: 2em; }
code {
    background: #f8f9fa;
    padding: 2px 6px;
    border-radius: 4px;
    font-family: 'Consolas', monospace;
}
pre {
    background: #2d3748;
    color: #e2e8f0;
    padding: 20px;
    border-radius: 8px;
    overflow-x: auto;
}
table { width: 100%; border-collapse: collapse; }
th { background: #3498db; color: white; padding: 12px; }
td { border: 1px solid #ddd; padding: 10px; }
#TOC {
    background: #f8f9fa;
    padding: 20px;
    border-radius: 8px;
    margin-bottom: 30px;
}

11 / 22

步驟 8：多文件合併

# 合併多個 Markdown 成一份完整文件
pandoc src\01-intro.md src\02-install.md src\03-usage.md `
    -o output\complete-guide.html `
    --standalone --toc --toc-depth=2 `
    --css=templates\tech-style.css `
    --metadata title="完整指南"

💡 多個 .md 檔案會按順序合併

12 / 22

步驟 9：版本控制

# 初始化 Git
git init
git add .
git commit -m "Initial docs"

# 每次更新文件
git add src\*.md
git commit -m "Update: API docs v1.1"

# 建立版本標籤
git tag v1.0.0

💡 技術文件應該納入版本控制

13 / 22

進階：從程式碼生成文件

請閱讀以下程式碼，為每個函數生成文件：

要求：
1. 函數名稱和用途
2. 參數說明（名稱、類型、說明）
3. 回傳值說明
4. 使用範例
5. 注意事項

程式碼：
```javascript
function calculateTotal(items, taxRate = 0.05) {
    const subtotal = items.reduce((sum, item) => sum + item.price, 0);
    return subtotal * (1 + taxRate);
}
```

14 / 22

進階：互動式 HTML 文件

點擊展開詳細說明

詳細內容在這裡...

pandoc input.md -o output.html

15 / 22

完整專案結構

📁 TechDocs/ ├── 📁 src/ │ ├── 01-intro.md │ ├── 02-install.md │ ├── 03-api.md │ └── 04-faq.md ├── 📁 templates/ │ ├── tech-style.css │ ├── tech-template.html │ └── tech-reference.docx ├── 📁 output/ ├── 📁 assets/ ├── build-docs.ps1 └── README.md

16 / 22

動手練習

完成以下任務：

建立 TechDocs 專案結構
使用 AI 生成一份簡單的 API 文件
建立 CSS 樣式檔案
轉換成 HTML 和 Word

17 / 22

練習答案

🔒 輸入密碼查看答案

# 1. 建立結構
mkdir D:\TechDocs; cd D:\TechDocs
mkdir src, templates, output

# 2. AI 生成 API 文件後存到 src\api.md

# 3. 建立 templates\style.css

# 4. 轉換
pandoc src\api.md -o output\api.html --standalone --toc --css=templates\style.css
pandoc src\api.md -o output\api.docx --toc

18 / 22

文件維護最佳實踐

✅ 定期更新文件與程式碼同步
✅ 使用版本控制追蹤變更
✅ 建立文件審查流程
✅ 收集使用者回饋改進
✅ 保持格式和用語一致

19 / 22

AI 輔助文件維護

請比較這份文件和最新程式碼，找出需要更新的地方：

舊文件：
[貼上舊文件]

新程式碼：
[貼上新程式碼]

請列出：
1. 需要新增的內容
2. 需要修改的內容
3. 需要刪除的內容

20 / 22

專案成果

功能	效果
標準化模板	確保文件品質一致
AI 生成	快速產出初稿
多格式輸出	滿足不同需求
自動化流程	一鍵建置所有文件

21 / 22

擴展可能

🔄 CI/CD 整合，程式碼更新自動重建文件
🌐 部署到靜態網站（GitHub Pages）
🔍 加入全文搜尋功能
📊 文件使用分析
🌍 多語言版本支援

22 / 22

本單元總結

                專案成果：
                完整的技術文件產生系統
多種文件類型模板
一鍵多格式輸出
AI 輔助內容生成

            

下一專案：批次報告製作 📊