技術文件怎麼寫

1. Preparation 準備階段

#準備階段的工作主要包括以下幾點：

·明確文檔需求

·明確文檔受眾

·界定文檔範圍

在寫文檔之前，需要明確文件需求。你要了解為什麼要寫這篇文檔，寫這篇文檔是為了達到什麼目的。

也要明確文檔受眾。受眾不同，內容就很可能不同。例如，面向開發人員和非開發人員/普通使用者的文檔，在內容的組織上就會不同。

還要界定文檔範圍。思考並確定這篇文件需要涵蓋哪些內容或模組，以及不會涉及哪些內容。這樣在之後蒐集資料的時候就會有所側重，寫的時候也不會模糊不定。

相關推薦：《php入門教學》

2. Research 研究階段

有過技術文件寫作經驗的小夥伴一定會深有同感，如果不理解某個東西，那麼給它寫文檔簡直太痛苦。

那麼當遇到一個讓你毫無頭緒的陌生主題時，該如何盡量避免這種痛苦呢？當然就是盡可能去理解了。

可是具體該如何做呢？簡言之，即蒐集資料。那又該如何蒐集資料呢？筆者認為，可以從以下幾點著手：

（1）對比較有代表性的同類產品或相似產品的相關文件進行研研，看看別人的文檔是怎麼做的。

在一無所知的時候，借鏡他人的經驗做法不失為一種好的選擇。透過對幾家產品的文檔進行對比，你就可以對自己要寫的文檔建立一個大致的框架。

要注意的是，借鏡不是照搬，只用來提供想法；產品不同，文件的結構規劃也會有差異。

（2）採用最有效的方法盡力蒐集與所寫文件相關的各種資料。

蒐集的資料經過 Technical Writer 的摘刪組織，很可能就會成為發布文件的一部分。

蒐集資料的方法有很多，像是網路搜尋、問卷、訪談、實驗，以及電子郵件討論、報告、技術文章等等。到底該使用哪一種方法要具體分析，需要你根據文件需求、Deadline、已有資料的豐富程度等因素，來選擇能快速且準確地蒐集到所需資料的方法。

有些主題的寫作，透過網路搜尋可能幾乎無法給你任何幫助。即便是這類內容，你也可以從開發人員那裡獲得一些資料，可以根據自己的需求請他們協助提供資料，抑或是透過內部系統中的開發說明和討論獲取所需資訊。

對於軟體類的產品文檔，即便有了一些技術資料，也往往需要 Technical Writer 自己使用一遍，從而對操作步驟有一個直觀的理解，獲得文檔寫作的一手資料。

3. Organization 文件架構

當資料蒐集得差不多的時候就可以組織這篇文件的具體結構了，之前對相似產品的研究或許可以在此時助你一臂之力。

對於常見的產品使用指南，一般按照安裝或使用的順序進行組織；對於其它一些非指南類的文檔，也應遵循一定的順序或邏輯。

此外，還需考慮該文件是否需要配圖，是否需要使用表格。如果需要配圖，明確是需要他人協助提供，還是需要自己完成。畫一個較複雜的圖也是一件蠻耗時的事情，花費的時間也需考慮。

有了詳細的文件架構之後，就可以進行下一步的寫作了。

4. Writing 文件寫作

如果做好了前幾步的工作，寫作將變得非常簡單，你只需把相應的內容準確地填到文檔架構中。在這個過程中，你需要寫一個個段落或具體的操作步驟。這是一個反映你的語言和寫作功底的時刻。

有的 Technical Writing 書籍中說到，在寫文件的時候不必在意文法、措詞和標點，認為這些細節應該在 Revision 階段完善。

Expand your outline into paragraphs, without worrying about grammar, refinements of language usage, or 
punctuation. 
Writing and revising are different activities; refinements come with revision. - Handbook of Technical 
Writing

我對此有不同的看法。一個合格的 Technical Writer 本身應該有良好的語言功底，像語法、措辭和標點這種最基礎的細節本就不該成為一個需要單獨解決的問題。規範的語法、得體的措詞、正確的標點應該已經成為一種不需要額外付出精力、也幾乎不會佔用額外時間的寫作習慣。

如果寫作的初稿比較粗糙，有許多需要修改的小細節，這必定會增加 review 時的工作量和時間成本，從而延緩文件流程。

或許，對於有精細化分工、每個人只負責一個小環節的大企業，可以採用這種方法。但是，對於快速發展、需要文件敏捷開發的新創公司，這種就不適用了。

5. Revision 審閱修改

寫完文件第一稿後，一般都需要進一步修改完善。這裡的 Revision 指的是 review 之後的修改，所以這一步也可以叫作：Review & Revision。

那麼需要誰來 review 呢？技術文件通常需要請其他小夥伴進行兩種review，即：

·Technical Review：從技術層面看文檔中的描述是否正確有效

·Language Review：從語言層面看文檔中的表達是否簡潔得體

收到reviewer 的回饋之後，Technical Writer 需要及時作出判斷和修改，有不明確的地方需和reviewer 討論確定。改完之後，再請 reviewer 看一下。如果又發現了新的問題，那麼還需要再修改。這個 review - revise 的過程可能會反覆幾次，很正常。

當然，在請他人 review 之前，Technical Writer 也可以先自己 review 一遍，盡量避免低級錯誤，不浪費他​​人的時間。

哈哈，問題又來了~通常，剛寫完一篇文章的人是很不情願再去看自己寫的東西的，此時就可以使用一些語法拼字檢查的小工具來協助你了。

如果你覺得自己夠細心，根本不需要小工具來協助你，我佩服你的能力，但還是建議用一下小工具。因為，你可能也會有狀態不好的時候，有疲勞打盹的時候，有不知道自己寫了一堆什麼鬼東西的時候……不要跟自己和小工具過不去。

6. Delivery 文件交付

等文件定稿之後，就可以在平台上發布了，一般很容易操作。不同的公司的文件發佈平台也會不一樣，Technical Writer 使用的寫作工具也不一樣。

文檔發布之後，並不代表結束。根據我的工作經歷，即便是已經發布的文檔，仍有可能有問題，無論是大公司還是小公司的文檔。例如：未發現的文字錯誤、失效的連結、與最新的產品已不符的描述和步驟等。 Technical Writer 需要及時跟進產品動態，以便及時更新文件。

以上是技術文件怎麼寫的詳細內容。更多資訊請關注PHP中文網其他相關文章！