技術檔案撰寫 | 玄貓の秘密

技術檔案的撰寫並非單純的技術轉譯，更需考量使用者經驗與資訊架構。良好的檔案導航設計如同地圖，引導使用者快速找到所需資訊。內容規劃則需兼顧技術細節與使用者需求，並透過持續的迭代更新，確保檔案的準確性和時效性。此外，有效的反饋處理機制能幫助檔案持續精進，提升使用者滿意度。

頁面結構與閱讀體驗

在設計檔案導航時，需要考慮讀者的閱讀習慣和行為模式。根據使用者反饋，大多數人希望檔案網站具有類別似Google的搜尋框，因為這能夠快速定位所需內容。然而，不同的團隊可能對導航結構有不同的期望，因此檔案導航設計是一個持續的實驗過程，需要根據使用者回饋和資料分析進行調整。

遵循導航模式

大多數讀者不會按照預設的導航路徑瀏覽檔案，他們可能會透過搜尋引擎、第三方網站連結或AI驅動的聊天機器人找到特定的頁面。因此，在設計導航時，必須考慮讀者可能從任意頁面進入檔案，並為他們提供到達該頁面的理想路徑。

檔案導航與選單設計

建立良好的檔案導航和選單結構是技術寫作中的重要環節。良好的導航設計可以幫助讀者快速找到所需的資訊，提高檔案的可用性和閱讀體驗。

頁面結構與閱讀體驗

遵循導航模式

檔案結構設計

檔案結構可以參考第二章中提到的內容型別進行設計，主要包括：

快速入門
參考資料

選單標題設計

選單標題應清晰簡潔，並遵循一定的命名規則。可以使用動名詞（以"-ing"結尾的動詞形式）來描述各個部分的功能和作用。例如：

  flowchart TD
 A[快速入門] --> B[]
 B --> C[參考資料]
 C --> D[進階功能]

圖表翻譯：

此圖示展示了一個基本的檔案結構設計。從「快速入門」開始，逐步引導讀者深入到「」和「參考資料」，最後到達「進階功能」。這種結構設計有助於讀者按照邏輯順序瀏覽和學習相關內容。

內部搜尋功能

為了幫助讀者快速找到所需內容，應在檔案中新增內部搜尋功能。許多免費和商業工具可以實作這一功能。透過在內容中新增後設資料，可以提高搜尋結果的準確性，幫助讀者找到相關資訊。

維護連結有效性

由於檔案內容可能會頻繁調整，因此保持連結的有效性非常重要。可以使用不同的工具和服務來檢查和更新失效的連結，以確保讀者能夠順暢地存取相關內容。

連結文字的最佳實踐

連結文字應具有描述性，讓讀者清楚地瞭解點選連結後將獲得的資訊。避免使用「點選此處」或「更多」等模糊的連結文字。理想的連結文字應該至少包含3到5個單詞，並準確描述連結內容。例如：

「如何組態Monito」
「完整的組態選項列表」

# 連結文字最佳實踐範例
def generate_link_text(description, url):
 """生成具有描述性的連結文字"""
 return f'<a href="{url}">{description}</a>'

# 使用範例
link_text = generate_link_text("如何組態Monito", "/configuring-monito")
print(link_text)

內容解密：

此程式碼定義了一個名為generate_link_text的函式，用於生成具有描述性的連結文字。函式接收兩個引數：描述內容和URL，並傳回一個包含描述性文字的HTML連結標籤。這種做法有助於提高連結的可讀性和搜尋引擎最佳化（SEO）效果。

技術寫作流程

在前兩章中，我們探討瞭如何架構檔案頁面以及有效的溝通所需的文法和風格基礎。具備這些知識後，我們現在準備進入本章的主題：與他人合作釐清需要記錄的內容以及評估其成效的過程。

建立技術檔案的過程與開發檔案的程式碼撰寫過程並無太大差異。技術檔案的建立永遠不是「完成」或「結束」的，而是一個持續迭代學習和改進的過程。

技術檔案建立的階段

如同軟體工程，技術檔案的建立過程包含以下主要階段：

範圍界定與需求收集
研究與產品測試
草擬與修改
回饋、測試與維護

這些步驟適用於建立新內容或新功能的檔案，但也適用於修復問題或調整現有內容的情況，只是可能省略某些步驟或簡化流程。

範圍界定與需求收集

在公司或專案中，檔案需求可能來自多個內外部來源，包括：

正在開發的新功能，通常來自產品負責人
已完成的新功能需要檔案支援
由技術寫作者識別出的功能缺口
由技術寫作者識別出的內容缺口
使用者或客戶回報的問題

首先要釐清目前的「完成」定義。這個定義可能會隨著時間變化，因此即便現在完成了某項內容，也不代表未來不會有變化。儘管有些變化可以預測，但仍有許多無法預料。因此，盡可能完整地完成當前工作，可以減少未來的負擔。

  flowchart TD
 A[開始建立檔案] --> B{收集需求}
 B --> C[定義完成標準]
 C --> D[進行研究與測試]
 D --> E[草擬檔案]
 E --> F[回饋與修改]
 F --> G[完成與維護]

圖表翻譯：

此圖示展示了技術檔案建立的主要流程。首先從「開始建立檔案」出發，接著進行「收集需求」，然後「定義完成標準」。完成標準定義後，進入「進行研究與測試」階段，隨後進行「草擬檔案」。草擬完成後，進入「回饋與修改」階段，最終完成檔案並進入「完成與維護」階段。此圖表清晰地展示了技術檔案建立的步驟和邏輯順序。

需求收集的挑戰

不同的利益相關者會有不同的期望。例如：

工程師可能希望涵蓋重要的技術細節
產品負責人可能關注新功能如何幫助使用者提高工作效率
行銷團隊可能希望比較競爭對手的產品功能

需要深入瞭解這些需求，而不僅僅是表面上的簡短描述。同時，也需要意識到不同角色的假設可能不同，例如：

工程師可能假設讀者已經瞭解某些技術細節
產品負責人可能假設特定的內容組織方式
行銷團隊可能希望以過度正面和銷售導向的語言描述功能

如何確設定檔案內容

如果要從頭開始建立整套檔案或主要功能的檔案，首先需要決定從哪裡開始以及需要多少檔案。檔案建立是一個迭代過程，尤其是在團隊規模較小或檔案編寫是兼職工作的情況下。

建議從最基本的部分開始，例如建立「入門」，然後確保有完整的參考檔案，如API或SDK函式的說明。這些內容可以構成「最小可行檔案」。入門足夠讓使用者開始嘗試產品，而參考檔案則能為熟悉產品的使用者提供所需的詳細資訊。

def document_priority(features):
 """決設定檔案撰寫的優先順序"""
 priority_list = []
 for feature in features:
 if feature['complexity'] > 5: # 複雜度高的功能優先
 priority_list.append((feature['name'], 'High'))
 elif feature['user_request'] > 10: # 使用者請求次數多的功能優先
 priority_list.append((feature['name'], 'Medium'))
 else:
 priority_list.append((feature['name'], 'Low'))
 return priority_list

內容解密：

此程式碼定義了一個名為document_priority的函式，用於決設定檔案撰寫的優先順序。函式接收一個包含功能資訊的列表作為輸入引數。根據功能的複雜度和使用者請求次數，函式將每個功能標記為高、中或低優先順序。首先，複雜度大於5的功能被標記為高優先。接著，使用者請求次數超過10的功能被標記為中優先。其他功能則被標記為低優先。這個函式幫助技術寫作者根據功能的重要性和複雜度來安排檔案撰寫的順序。

研究與產品測試

對於技術檔案的撰寫，沒有什麼能取代實際操作和測試產品的過程。即使沒有技術背景，也可以透過時間累積相關經驗，而新鮮的視角往往能發現開發者未曾預料的問題。

在小公司中，技術檔案的編寫者往往是繼開發者之後第一批嘗試新產品或新功能的人。我們位於工程、產品、行銷和客戶支援之間的角色，使我們對產品有著獨特而全面的視角。

  sequenceDiagram
 participant Developer as 開發者
 participant TechnicalWriter as 技術寫作者
 participant ProductOwner as 產品負責人
 Developer->>TechnicalWriter: 提供新功能資訊
 TechnicalWriter->>ProductOwner: 詢問產品需求
 ProductOwner->>TechnicalWriter: 回覆產品資訊
 TechnicalWriter->>TechnicalWriter: 研究與測試產品
 TechnicalWriter->>Developer: 詢問技術細節
 Developer->>TechnicalWriter: 提供技術細節
 TechnicalWriter->>TechnicalWriter: 草擬檔案

圖表翻譯：

此序列圖展示了技術寫作者在建立檔案過程中的主要互動流程。首先，開發者向技術寫作者提供新功能的資訊。技術寫作者接著向產品負責人詢問產品需求，並獲得回覆。隨後，技術寫作者進行產品的研究與測試，並向開發者詢問技術細節以取得更多資訊。最後，技術寫作者根據收集到的資訊進行檔案草擬。這個流程圖清晰地展示了技術寫作者在檔案建立過程中與不同角色之間的協作關係。

技術寫作流程深度解析

身為一名技術寫作者，特別是具備電腦科學背景的「技術型」寫作者，我深刻理解編寫高品質技術檔案的挑戰與機遇。本文將深入探討技術寫作的流程，涵蓋從學習產品到撰寫和修改草稿的全過程，並結合實際經驗提供寶貴的見解。

學習與理解：技術寫作的基礎

要編寫出色的技術檔案，首先需要深入瞭解所要記錄的產品或系統。這個過程並非易事，尤其是當面對複雜的技術系統時。作為技術寫作者，我們需要具備學習如何學習的能力，提出正確的問題，並找出關鍵資訊。

假設零知識：消除先入為主的偏見

在開始學習新產品或系統時，保持「假設零知識」的心態至關重要。這意味著拋開個人偏見和既往經驗，從使用者的角度出發。為了實作這一點，可以建立一個內部檢查清單，涵蓋以下方面：

作業系統及其版本和架構
安全限制和IT團隊的規定
常見的依賴項，如版本控制系統和語言執行環境版本
程式語言規範和模式
專案或環境設定的常見流程

實際操作：親身體驗產品

理論知識固然重要，但親自操作產品或系統才能真正理解其運作方式。這可以透過以下方法實作：

使用容器執行時技術（如Docker或Podman）建立乾淨、可重複的環境
利用程式語言版本管理器在不同版本間切換
使用虛擬機器測試不同作業系統或組態
重置應用程式至預設狀態以模擬新使用者的體驗

提出正確的問題

在學習過程中，提出正確的問題至關重要。這需要與團隊成員、協作者以及產品本身進行互動。透過實際操作和實驗，可以更好地理解產品的運作方式，並提出更有針對性的問題。

撰寫與修改：從初稿到終稿的旅程

完成初步學習後，便可以開始撰寫技術檔案。與其他形式的寫作一樣，單一草稿往往不足以達到理想效果。因此，撰寫和修改草稿成為技術寫作流程中的重要環節。

取得反饋：與利益相關者的互動

完成初稿後，需要邀請相關利益者進行審閱並提供反饋。這個過程可能耗時，但對於確保技術檔案的準確性、公司優先事項和語言清晰度至關重要。

處理反饋：平衡多方意見

在取得反饋時，可能會遇到兩種極端情況：一是幾乎沒有反饋，二是反饋過於龐雜。對於這兩種情況，需要採取不同的處理策略：

若反饋不足，可安排特定的會議徵求意見
面對大量反饋時，應提出具體問題以引導審閱者

以下是一些可供參考的問題：

您對所讀內容有何看法？
如果可以更改所讀內容，您會修改哪些方面？
哪些部分容易理解，哪些部分難以理解？為什麼？
您如何向他人解釋這些內容？
這些內容是否滿足您的需求？如果沒有，為什麼？

篩選反饋：聚焦關鍵資訊

在處理大量反饋時，需要區分不同型別的意見：

來自主題專家的技術性反饋
語言、語法和拼寫方面的建議

在早期階段，應優先考慮主題專家提供的技術性反饋，而非語言細節。這有助於確保技術檔案的準確性和相關性。

結語

技術寫作是一項需要持續學習和改進的技能。透過深入瞭解產品、撰寫初稿、取得並處理反饋，我們可以建立出高品質的技術檔案。這個過程不僅需要技術寫作者具備強大的學習能力和溝通技巧，也需要團隊的密切協作。只有這樣，才能製作出既準確又易於理解的技術檔案，滿足使用者的需求。

技術寫作流程視覺化

  flowchart TD
 A[開始學習產品] --> B{建立內部檢查清單}
 B --> C[實際操作產品]
 C --> D[提出正確的問題]
 D --> E[撰寫初稿]
 E --> F[取得反饋]
 F --> G{處理反饋}
 G -->|反饋不足| H[安排會議徵求意見]
 G -->|反饋過多| I[提出具體問題引導審閱者]
 H --> J[修改草稿]
 I --> J
 J --> K[最終定稿]

圖表翻譯：

此圖示展示了技術寫作的流程。首先，從學習產品開始，建立內部檢查清單以確保全面理解。接著，透過實際操作產品來取得第一手經驗，並在此基礎上提出正確的問題。完成初步學習後，開始撰寫初稿。隨後，取得相關利益者的反饋，並根據反饋的多寡採取不同的處理策略。若反饋不足，則安排會議徵求意見；若反饋過多，則提出具體問題以引導審閱者。最後，根據反饋修改草稿，直至完成最終定稿。

程式碼範例與解析

以下是一個簡單的Python函式，用於計算數字列表的平均值：

def calculate_average(numbers):
 """
 計算數字列表的平均值

 Args:
 numbers (list): 包含數字的列表

 Returns:
 float: 數字列表的平均值
 """
 total = sum(numbers) # 加總所有數字
 count = len(numbers) # 計算數字數量
 return total / count if count > 0 else 0 # 避免除以零錯誤

內容解密：

此函式名為calculate_average，接受一個數字列表作為輸入引數。首先，使用內建的sum函式計算列表中所有數字的總和。接著，透過len函式取得列表中的數字數量。最後，傳回總和除以數量的結果，但需特別處理列表為空的情況，以避免除以零的錯誤。這種實作方式簡潔高效，適用於大多數平均值計算的場景。

技術寫作的最佳實踐

保持中立與客觀：技術寫作應當客觀呈現資訊，避免個人情緒或主觀偏見。
使用清晰簡潔的語言：避免使用過於複雜或專業的術語，以確保內容易於理解。
結構清晰，層次分明：採用邏輯清晰的結構，使讀者能夠輕鬆跟隨思路。
提供實際範例：透過具體的範例幫助讀者更好地理解抽象的概念或技術細節。
持續更新與維護：技術檔案需要隨著產品或技術的更新而定期更新，以保持其相關性和準確性。

未來展望

隨著技術的快速發展，技術寫作也在不斷進化。未來，我們可以期待看到更多創新性的技術寫作工具和方法的出現。同時，技術寫作者需要持續提升自己的技能，以適應不斷變化的技術環境和使用者需求。

檔案編寫的反饋處理與維護

撰寫技術檔案是一個持續迭代的過程，而處理反饋是這個過程中的重要環節。來自內部和外部的反饋不僅有助於提升檔案的品質，也能改善產品的使用者經驗。本章將深入探討如何有效地處理反饋、管理檔案發布後的維護工作，以及如何利用反饋來持續改進檔案。

處理內部反饋

在檔案發布之前，通常會經過多輪內部審閱。審閱者的反饋可能五花八門，有些是有建設性的，有些則可能與檔案的核心內容無關。作為技術檔案編寫者，需要學會篩選和處理這些反饋。

篩選與回應反饋

區分反饋型別：首先，需要區分哪些反饋是有用的，哪些是可以稍後處理的，以及哪些是與檔案無直接關係的意見或建議。
感謝與記錄：對於那些與當前檔案內容無直接關係的反饋，應禮貌地表示感謝，並記錄下來以備日後參考。
處理有用反饋：對於有用的反饋，需要仔細評估其合理性，並決定是否採納。作為檔案編寫者，雖然不一定是產品的技術專家，但需要具備清晰闡述複雜技術概念的能力。
禮貌地拒絕不採納的反饋：當反饋不被採納時，應以友善、專業的方式進行溝通，解釋不採納的原因。有時，這樣的做法能夠得到審閱者的理解，但也可能引發進一步的討論。

保持溝通的專業性

在書面溝通中，很容易出現誤解或情緒化的回應。因此，保持溝通的清晰、耐心和開放態度至關重要。這不僅有助於減少誤解，也能提高溝通的效率。

確定反饋迴圈的結束

什麼時候可以結束反饋迴圈並發布檔案更新？這取決於行業的風險等級和檔案錯誤的潛在後果。在高風險行業，如醫療、金融或工業領域，檔案變更通常需要經過嚴格的審核和批准才能發布。

在大多數其他行業中，檔案的迭代更新是一個持續的過程。由於檔案永遠不會真正「完成」，因此需要在完善內容和及時發布之間找到平衡。通常，外部壓力（如產品發布日期或行銷活動）會促使檔案的發布。

檔案發布後的反饋與維護

檔案發布後，真正的考驗才剛剛開始。來自使用者的反饋是改進檔案的重要依據。使用者可能會透過多種通路提供反饋，包括：

取得使用者反饋的途徑

開源檔案倉函式庫的議題（Issues）：使用者可能會在檔案的開源倉函式庫中提交議題，報告他們遇到的問題。
產品程式碼倉函式庫的議題：如果產品程式碼也是開源的，使用者可能會在產品程式碼倉函式庫中提交與檔案相關的問題。
反饋小工具：在檔案中加入反饋小工具（如評論框、「這有幫助嗎？」選項等）可以方便使用者直接提供反饋。
商業支援請求：使用者在使用產品過程中遇到的問題，也可能透過商業支援請求間接反饋給檔案編寫團隊。
社群論壇和部落格文章：使用者可能會在社群論壇、部落格或技術演講中分享他們對產品和檔案的體驗和意見。

處理使用者反饋的挑戰

過濾無關或垃圾資訊：特別是在公開通路上，反饋中可能混雜著大量無關或垃圾資訊，需要進行過濾。
識別與檔案相關的反饋：使用者提供的反饋可能並不總是與檔案直接相關，而是與產品本身的問題或需求相關。需要學會從中識別出與檔案改進相關的部分。

利用反饋持續改進檔案

雖然使用者反饋可能不總是直接針對檔案，但其中往往包含有價值的資訊。這些資訊不僅可以幫助改進檔案，也可以為產品改進提供參考。

將反饋轉化為行動

轉交產品相關反饋：將與產品相關的反饋轉交給相關團隊，幫助改進產品。
改進檔案：利用使用者反饋，找出檔案中需要改進的部分，特別是在使用者容易混淆或挫折的地方提供更清晰的說明。

透過積極收集和處理反饋，技術檔案編寫者可以不斷改進檔案品質，更好地滿足使用者的需求。這是一個持續的過程，需要耐心和細緻的工作。

  flowchart TD
 A[開始處理反饋] --> B{區分反饋型別}
 B -->|有用反饋| C[評估並處理反饋]
 B -->|無關反饋| D[記錄並感謝]
 C --> E[決定是否採納反饋]
 E -->|採納| F[更新檔案]
 E -->|不採納| G[禮貌拒絕並解釋]
 D --> H[結束當前反饋處理]

圖表翻譯：

此圖示展示了處理反饋的基本流程。首先，系統會開始處理反饋，接著區分反饋的型別。如果反饋是有用的，系統會進一步評估並處理；如果反饋是無關的，則記錄下來並對提供者表示感謝。對於有用的反饋，會決定是否採納，採納的反饋會用於更新檔案，而不採納的則會以禮貌的方式拒絕並給出解釋。最終，所有反饋處理完畢後，流程結束。這個流程清晰地展示瞭如何系統地處理和利用反饋來改進檔案。

玄貓

技術愛好者，專注於分享程式開發、雲端技術與 AI 應用的心得體會。