# 將你的程式碼文件化

寫文件通常被認為是麻煩、無聊的任務。如果從使用者的角度來思考、建立文件，就會是一件有趣的事。

## 好讀文件的面向

文件的目的是讓讀者了解軟體的用途和使用方法。

清楚好讀的文件有四種特性：
* 傳達軟體設計背後的概念
* 說明軟體行為的規格
* 說明如何執行特定動作
* 具備可用性 (usability)

### 傳達軟體設計的概念

好的文件應該要解釋軟體的用途，讓潛在的使用者能夠知道如何使用。同時，文件也應介紹重要的術語、說明文件架構，讓使用者能夠了解文件內容。

要清楚傳達軟體概念，最重要的是從使用者的觀點出發：
* 確認誰是使用者 (他們是誰以及他們的技術水準)
* 確認使用者對問題領域了解多少
* 確認文件內容的抽象化程度以及如何提供好的概念類比：讓使用者能夠就目前的技術知識理解文件內容

比較下列兩段文字：

SuperCoolTypeAnimator 是一個 SVG 字形動畫工具，允許創建並逐幀操縱源字形與相應目標字形之間的過渡，動態計算適當的過渡錨點。

SuperCoolTypeAnimator is an SVG glyph animation utility that allows the creation and frame-by-frame manipulation of transitions between source glyphs and their respective target glyphs,calculating appropriate transitional anchors on the fly.

SuperCoolTypeAnimator 是一個 JavaScript 函式庫，讓您能夠輕鬆地將小段文字從一個字體樣式動畫到另一個字體樣式。

SuperCoolTypeAnimator is a JS library that allows you to animate small pieces of text from one typeface to another typeface with ease.

使用術語是把雙面刃：建議只使用大家(應該)都懂的基本術語，避免使用太艱深或是自己發明的術語。

### 說明軟體行為的規格

好的文件會清楚說明軟體介面的特性和行為。

說明軟體規格通常是文件裡最簡單好寫的部份：
* 基本上就是在描述程式碼 (包含測試的內容)：如果覺得很難描述，很可能代表程式碼本身寫得過於複雜。
* 可以自動生成：有不少工具會使用程式碼中的靜態型別或註解來生成文件。
* 格式固定：API 該傳入什麼參數並解釋每個參數的意義和用法，還有輸出值是什麼。

最重要的是，要明確讓使用者了解該怎麼使用這些 API。

removeWords( subjectString, wordsToRemove );

* `subjectString(String)`： 這是指定的詞將從中刪除的字串。如果您未傳遞 String 類型，則傳遞的值將轉換為字串。
* `wordsToRemove(Array)`：這是包含您希望刪除的詞的陣列。null 或空陣列將不會刪除任何詞。

注意：
* 儘量提供足夠的資訊，讓其他沒有一樣背景知識的工程師也能順利使用。必要的時候，也要提供該領域的相關知識。
* 確保資訊正確、即時：從註解自動產生文件，可以減少資訊過時的問題
* 提供使用範例或教學文章

### 說明如何執行特定動作

好的文件要教導使用者如何完成常見的任務。這些內容通常叫做 walkthroughs、tutorials (教學文章/影片)、how-tos 或 recipes。

教學文件建議內容：
* 明確指出所需的硬體、軟體環境和效能需求，以及在執行前應該要完成的事
* 教學步驟必須明確，讓使用者可以跟著模仿。儘量提供指令範例，也要告知使用者怎麼確認自己成功達成步驟。可以的話，也試著說明每個步驟的意義。
* 教學文件設定可以達成的目標，而且使用者能夠觀察到自己已達成目標。

這部份的文件是最有挑戰性的：擔任指導者的角色，同時還要以不了解這個軟體的人的角度出發。

https://support.apple.com/zh-tw/guide/app-store/fir9b2ea074e/mac

### 具備可用性 (usability)

先前的部份與「文件內容」有關，可用性則關於「如何呈現內容」：

* 內容份量適中，太多太少都不好。
* 內容要一致、正確。
* 文件要有清楚、分層的架構。
* 文件要容易搜尋、瀏覽：集中在同一地方、能夠搜尋而且有 accessibility。
* 美觀且注重排版

由於每個使用者的偏好不同，通常不會以一份教學文件打天下，而是會用不同方式提供教學內容：研討會、白皮書、教學文章、FAQ、教學影片等等。

### 處處皆文件

如果把文件定義為「學習軟體的方式/管道」，會發現有很多種類的文件，例如：
* 圖片、圖表
* 多媒體教學 (影片、podcast、投影)
* 公開的 QA 討論 (GitHub issues)
* 社群論壇 (StackOverflow)
* 研討會、專題討論、技術小聚
* 官方支援 (實體或線上)
* 課程
* 測驗
* 錯誤處理流程和訊息

### 當讀者沒有技術背景時

當開發人員與不具技術知識的終端使用者或利害關係人 (例如公司管理層或非技術部門的人員)，必須調整溝通的方式：
* 調整內容抽象化的程度
* 避免太過艱深的術語
* 持續取得對方的回饋：不斷向對方確認是否能夠了解內容，不要因為他們沒有任何表示就當作他們都聽懂。