完整的技術寫作流程是怎樣的？

Foreword

如果你有過 Technical Writer 實習或工作經歷，那麼對技術寫作的流程應該已經了解。

當然，在很多大公司里，你參與的很可能只是這個流程的某一個環節。例如，你只負責寫，或者只負責 review，或者只負責文檔架構。相比之下，在創業公司里，可能會參與多個環節。

如果你是尚未畢業而且也沒有相關實習經歷的在校生，或者已經工作但有意轉行做 Technical Writer 的小夥伴，那麼可能對技術寫作流程仍存疑惑，或者一知半解。

不同公司技術文檔流程的劃分可能略有差異，但從本質上來看，則大同小異。

無論你在這個流程中的哪個環節，從宏觀上了解整個流程有助於讓你的認識更加清晰，也有助於在有需求時從容地承擔其它環節的工作。

這裡跟大家分享一個完整的技術文檔寫作流程，你只需記住六個單詞即可。如下圖所示：

再說明一下，你從工作中已經了解或即將接觸的技術寫作流程不一定與上圖完全一致，但一個完整的流程一般都會涵蓋這些內容，區別多半是主觀劃分而已，這一點不必拿出「大家來找茬」的精神死磕哦~

1

Preparation 準備階段

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

明確文檔需求

明確文檔受眾

界定文檔範圍

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

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

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

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 一遍，盡量避免低級錯誤，不浪費他人的時間。

哈哈，問題又來了~

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

我在之前的一篇文章Technical Writer 日常工作中好用的小工具中有推薦，有需要的小夥伴可以戳鏈接去瞅瞅~

如果你覺得自己足夠細心，根本不需要小工具來協助你，我佩服你的能力，但還是建議用一下小工具。

因為，你可能也會有狀態不好的時候，有疲勞打盹的時候，有不知道自己寫了一堆什麼鬼東西的時候……不要跟自己和小工具過不去。

6

Delivery 文檔交付

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

文檔發布之後，並不代表著結束。根據我的工作經歷，即便是已經發布的文檔，也依然有可能存在問題，無論是大公司還是小公司的文檔。

例如：未發現的文字錯誤、失效的鏈接、與最新的產品已不匹配的描述和步驟等。Technical Writer 需要及時跟進產品動態，以便及時更新文檔。

Afterword

寫技術文檔不是一勞永逸的，只要產品在更新，就需要 Technical Writer 一直維護下去。

以上分享的是一個完整的技術文檔從零到有的過程。日常工作中，有時不需要從頭開始，而只是對原有文檔的增刪修改，那就可以省去一些相應的環節。

如果你也是一枚 Technical Writer，也期待聽到你對技術寫作流程的見解，歡迎留言交流哦~

Reference:

1. Handbook of Technical Writing (10th Edition), by Gerald J. Alred, Charles T. Brusaw, and Walter E. Oliu, Bedford/St. Martin』s

2. https://techwhirl.com/what-is-technical-writing

你可能想讀

技術傳播那些事兒

知乎專欄：https://zhuanlan.zhihu.com/tc-fun

簡書專題：http://www.jianshu.com/c/c61708ae5bd1

喜歡這篇文章嗎？立刻分享出去讓更多人知道吧！