建立有效的技術文件

有效的特性文件對於提升使用者使用該特性的體驗至關重要。好的文件就像拼圖中的一塊，能讓一切都清晰明瞭——這是鼓勵使用者採納特性的關鍵。

為了幫助您建立有效的技術文件，本文概述了技術寫作的核心原則。同時，它還重點介紹了建立清晰易懂的文件的最佳實踐。運用這些技術寫作原則有助於我們保持 MDN 內容的高質量。無論您是記錄自己的專案或產品，還是在各種環境下為技術內容做貢獻，都可以透過遵循這些最佳實踐來提高工作質量。

力求清晰、簡潔、一致

這三個“C”（Clarity, Conciseness, Consistency）構成了技術寫作的核心原則。它們能幫助您在撰寫高質量文件方面取得長足的進步。

清晰性 (Clarity)

為實現寫作的清晰性，請遵循以下指南

使用簡單的詞語和清晰的語言。請牢記您的受眾，特別是當其中包含非英語母語者時。
明確誰需要執行操作。嚴格來說，不必強制使用主動語態。但是，當您希望明確誰需要執行操作時，應該使用它。例如，請明確是事件觸發了某個函式，還是使用者需要顯式呼叫該函式。
清晰地介紹和解釋新術語。這有助於為後續文件中的概念奠定基礎。
為避免歧義，請清楚地指定代詞。

如果“it”、“this”和“these”在特定語境中可能指代不止一個事物，請用專有名詞替換它們。
力求每句話只表達一個觀點，以提高可讀性。
每段只堅持一個主要觀點。段落中的每個句子都應該與其前面的句子在邏輯上相關聯。想象一下，段落中的每個句子都是鏈條中的一個環節。如果您拿起第一個環節，鏈條中的其他環節應該會依次連線，形成一個連續的序列。句子之間就應該這樣連線，確保單個想法的流暢過渡。

簡潔性 (Conciseness)

保持句子簡短。這會自動提高文件的可讀性和清晰度。它也有助於快速理解。長句由於結構複雜，可能更難快速理解。

根據常見的可讀性標準，目標是每句 15-20 個單詞。

有關句子長度和可讀性策略的更多見解，請參閱簡單句子（在 https://readabilityguidelines.co.uk 上）以及維基百科上的流行可讀性公式，包括 Flesch-Kincaid 指數。

一致性 (Consistency)

在整個文件中使用相同的術語，以確保讀者體驗的無縫銜接。例如，如果您開始將“使用者代理”稱為瀏覽器，請始終保持該術語。這可以避免因交替使用意義相同但詞語不同的詞語而造成的混淆。

此外，在整個文件中保持一致的詞語大小寫和統一的格式風格。這些做法不僅能提高可讀性，還能使您的文件呈現出專業性。

有條理地組織內容以獲得最大效果

在組織內容時，應用與組織程式碼相同的原則：花一些時間設定明確的目標，並考慮文件的預期結構。確保每個子部分都逐步地為實現這一目標做出貢獻。

從引言開始

在引言中，首先描述您要記錄的特性。然後，透過解釋瞭解該特性的好處來設定背景。這可以包括描述該特性在現實生活中可能很有用的場景。您為主題新增的相關性越多，讀者就越容易理解和參與到內容中。

有邏輯地推進

以下問題可以幫助您確保內容進展有條理

您的文件結構是否能引導讀者從基礎概念到更高階的概念？是否有部分介紹“是什麼”以建立基礎，然後再深入探討“為什麼”和“怎麼做”？考慮文件結構是否能反映該主題的自然學習路徑。將文件結構與自然的學習過程相匹配，有助於讀者循序漸進地構建知識，並提升整體學習體驗。
概念性部分之後是否有足夠的操作指南或示例？
考慮內容的流程。它是否遵循邏輯順序——從一個句子到下一個句子，從一個段落到下一個段落，從一個章節到下一個章節？每個章節是否都邏輯地建立在之前呈現的資訊之上，避免內容突然跳躍或出現空白？

此外，在處理草稿時，請始終問自己

這句話我是在回答讀者的哪個問題？
我能新增一個簡單的或現實生活中的用例來解釋這個概念嗎？

包含示例

想象一下，您正坐在一旁向某人解釋概念。預見他們的疑問並在您的寫作中解答。利用這種方法新增儘可能多的相關示例。

新增示例時，不要僅限於程式碼；包含非程式碼場景來展示特性的實用性。這有助於讀者更好地理解概念，也能迎合不同的學習風格。考慮提供現實世界的場景或用例，來說明該特性或概念在實際情況中的應用。

最佳化文件結構和長度

評估您的文件結構，確保其保持邏輯和均衡的層級。

確保每個章節和子章節都有明確的目的和足夠的內容。
查詢主要章節只包含一個子章節（孤節）的情況，例如 H2 章節下只有一個 H3 章節。這表明您需要重新組織內容或進行一些補充。
檢查是否有更低級別的標題，如 H4。過多的子章節會讓讀者感到不知所措，難以理解資訊。在這種情況下，考慮將內容呈現為專案符號列表，以幫助讀者更有效地記住要點。這種方法有助於簡化層級結構，也方便導航。
雖然每個章節都應該有足夠的內容，但也要注意整體長度。如果任何章節變得過於冗長，會讓讀者感到不知所措。將大型章節拆分成多個邏輯子章節，或將內容重組為新的章節和子章節。將內容分組為易於理解的小塊有助於保持專注並改善讀者的導航。

仔細校對您的文章

有一個方面怎麼強調都不為過，那就是對您所寫內容進行**自我審查**和**校對**的重要性。無論您是在建立長篇文件還是短段落，這一步都至關重要。

花時間全面審查您的作品將幫助您找出那些流程不順暢或可以改進清晰度的部分。在自我審查期間，目標是發現並消除冗餘（不增加價值的觀點重複）和重複（過度使用詞語或短語）。這些改進將確保您的文件清晰連貫，並按預期傳達您的想法。

校對，然後休息一下，再進行第二次審查。之後再提交您的工作。拼寫檢查器可以標記拼寫錯誤，但可能無法標記詞語的錯誤使用，例如意外地將“he”用作“the”。最好休息一下，用清新的視角回來，捕捉您可能錯過的任何錯誤。請密切注意識別語氣、風格、時態或格式上的一致性問題，並進行必要的調整。

其他建議

為了提高文件的清晰度和可訪問性，請牢記以下指南和建議。要深入瞭解任何主題，請隨時查閱我們的寫作風格指南。

專案符號列表與編號列表：列表通常使文件更易於掃描。當專案沒有特定順序時，使用專案符號列表。當步驟需要按特定順序執行時，使用編號列表。在開始列表之前，始終包含一個引導句以提供上下文。
逗號：在引入性從句後使用逗號，以提高可讀性並理清句子結構。在列表中分隔專案時使用逗號以確保清晰性。
替代文字：始終為您新增到內容中的圖片提供替代文字。這使得使用螢幕閱讀器的使用者也能訪問您的文件。除了圖片，請確保影片和音訊檔案附有描述性文字。

描述性連結文字：確保每個連結文字在脫離上下文時也能清晰明瞭，並清楚地指示連結指向何處。描述性連結文字也有助於螢幕閱讀器的使用者理解連結的目標。例如，使用“閱讀我們的寫作風格指南以瞭解更多”而不是“點選這裡以瞭解更多”。

包容性語言：讓您的文件對所有人都是受歡迎的。努力使用尊重和承認受眾多樣性的詞語。

總結

本文到此結束。希望這些建議能幫助您快速回顧技術寫作的最佳實踐。請記住，學習如何建立有效且易於使用的文件是一個持續的過程。它始於瞭解您的受眾以及您文件的目標。透過運用這些技術寫作原則和技巧，您一定能夠提高文件的清晰度和整體質量。

如果您學到了新東西，或者有任何想法引起了您的共鳴，請告訴我。我也很想聽聽您在技術文件工作流程中使用的任何最佳實踐。在 Mastodon 或 Discord 上與我們分享。