# 技術文件撰寫指引

## 撰寫目的

技術文件的核心目標是清楚傳達技術資訊，使讀者能夠理解、操作或查詢相關內容。
好的技術文件不僅幫助開發者、使用者或維護人員高效完成工作，還能提高產品品質、
減少支援成本，並促進知識傳承。

## 重點資訊

> [!Important]
> * 確定目標讀者
> * 文章結構層次分明 (章節分段)
> * 重點訊息 highlight
> * 內文清晰簡潔
> * 不求美觀但版面整齊乾淨
> * 持續修改更新

>[!Tip]
> * 善用超鏈結的方式來精簡內文
> * 引用文獻時附上文章標題比直接貼網址來的清楚
> * 避免太近的段落間距
> * 過多文字擠在一起不容易閱讀
> * 利用圖片或下拉選單等方式讓讀者更容易掌握重點
> * 下拉選單可以作為主題細節的補充說明來避免發散重點
> * 太長的文件資訊可將內容拆分
> * 拆成兩個文件或是放入 Appendix

## 不同類型文件架構

> [!Note]
> [Diátaxis](https://diataxis.fr/) 將常見文件類型分為四項:
> * 教學 (Tutorial)
> * 快速上手產品或系統
> * 操作指南 (How-to)
> * 完成特定工作或目標的步驟指引，不需要解釋背後原理
> * 解釋型文件 (Explanation)
> * 解釋系統運作原理和概念邏輯
> * 參考文件 (Reference)
> * 提供詳細的技術規格，如API參數等

### 教學型文件
:::spoiler

<br/>

目標:
* 幫助新手循序漸進地學習某個技術或功能，通常是`新手友好`的循序漸進指南

特點:
* 簡單、逐步引導、確保讀者能完成每一步並獲得結果

常見架構:

[標題]：如何 [完成某個任務]

1. 前言
- 教學的目的
- 受眾（optional）
- 前置知識或技能（optional）

2. 前置準備
- 必要條件（軟體、環境、帳戶等）
- 安裝與設定（optional）
- 必要的背景知識簡介（optional）

3. 教學步驟
- 清楚的指引
- 逐步拆解過程
- 相關的指令或範例程式碼（optional）

4. 文獻或後續學習資源
- 引用文獻
- 進階教學或相關資源

:::

---

### 操作指引文件
:::spoiler

<br/>

目標:
* 幫助使用者快速完成特定任務或解決某個問題

特點:
* 針對`特定需求撰寫`，而非全面性介紹
* 提供`清楚的步驟` 確保讀者能快速完成任務
* 適合使用`指令`、`圖解`或`範例程式碼`來說明

常見架構:

[標題]：如何 [解決某個問題或完成某個操作]

1. 目標
- 本指南適用的情境
- 需要的前置條件（optional）

2. 操作步驟
- 明確的指令或操作方式
- 附加示例程式碼 (optional)
- 圖片或表格輔助（optional）

3. 常見錯誤與解決方案 OR 注意事項
- 錯誤類型及解決方法
- 其他可能遇到的問題

4. 相關資源
- 官方文件連結
- 進一步閱讀建議

:::

---

### 解釋型文件
:::spoiler

<br/>

目標:
* 深入探討技術概念，幫助讀者理解`why`

特點:
* 理論性較強，通常不包含完整步驟
* 大多包含範例或圖解

常見架構:

[標題]：[技術概念] 深入解析

1. 概述
- 什麼是 [技術概念]？
- 為什麼它很重要？
- 適用的情境與使用案例

2. 主要原理
- 描述該概念
- 技術細節
- 可視化圖表或範例解釋 (例如:流程圖)

3. 實際應用
- 這個概念可以如何應用
- 可能的優勢與挑戰 (optional)

4. 文獻總結
- 主要概念回顧 (optional)
- 延伸閱讀或進一步學習資源

:::

---

### 參考型文件
:::spoiler

<br/>

目標:
* 提供完整、可查詢的技術資訊，如 API、指令、參數設定等

特點:
* 結構化
* 清晰、有表格與範例
* 避免冗長描述

==若是撰寫 API 文件，可以使用 Postman, Swagger 等工具生成相關文件==

常見架構:

[標題]：[技術功能或指令] 參考文件

1. 簡介
- 這個指令/API/功能的用途
- 適用的系統或版本

2. 語法
- 程式碼或指令範例
- 變數或參數的基本說明

3. 參數說明
| 參數         | 類型  | 預設值  | 描述 |
|--------------|------|--------|--------------------|
| `param1`     | int  | `10`   | 這個參數的用途 |
| `param2`     | bool | `false` | 是否啟用某功能 |

4. 返回值（for API）
- 回傳資料的格式與範例

5. 使用範例
- 基本用法
- 進階設定（optional）

6. 錯誤代碼（optional）
| 錯誤碼  | 說明 |
|---------|---------------------------|
| `E001`  | 參數缺失 |
| `E002`  | 無效的輸入 |

7. 相關資源
- 官方文件
- 其他相關技術文件

:::

<br/>

## HackMD 文件範本
:::success
HackMD 本身也有提供文件模板可以直接使用
:::
:::spoiler
### 建立步驟說明
>[!Tip]
>STEP 1
>* 新增一篇筆記時，點選左上方的加號 icon，選擇`從範本新增筆記`
>
>
>STEP 2
>* 在右邊選單選擇想使用的版型，左邊可以預覽，確認好後按下`套用此範本`
>

:::

<br/>

## 相關資源
[Diátaxis](https://diataxis.fr/)
[如何寫好技術文件？給作為軟件工程師的你，寫出容易明白的文件](https://roulesophy.github.io/20230712-how-to-write-technical-documents/)
[[筆記] 如何寫一份技術文件](https://blog.bear-su.dev/2023/10/22/note-how-write-tech-document/)
[使用者不會用我家的軟體產品怎麼辦？寫 Tutorial 技術文件的 6 個訣竅，幫助你提升試用產品的轉換率](https://vocus.cc/article/6528faaefd8978000194fa24)