從事軟體開發十餘年，除了寫點程式，也寫文章、出版電子書。
技術寫作基礎概念：Docs as a product 與 content first
目標讀者：軟體開發人員、DevOps 工程師、產品經理
概要
上一篇筆記提到 Docs as Code，指的是以跟寫程式一樣或相似的工具與流程來製作文件。這篇筆記要再介紹兩個有關技術文件寫作的基礎觀念：
Docs as a product，指的是把「技術文件」當成一個產品來發展和維護。
Content first，即內容優先。既不是工具優先、平台優先，也不是美觀樣式優先。
Docs as a product
Documentation as a product 簡稱 Docs as a product，指的是把「技術文件」當成一個產品來發展和維護。
乍聽之下似乎很直觀，沒必要特別強調。但實際上，每個人寫出來的技術文件不會完全一樣，而文件對於目標讀者是否「有用」才是最要緊的。並不是說，每個人今天搞懂了一項技術或 know-how，鍵盤抄起來劈哩啪啦開始打字，便都可以立刻成就一篇易讀易懂、對讀者有用的文章。而且，如果本身肩負 DevOps 相關工作，日常的程式開發、問題排查、技術支援等工作可能已占滿大部分的時間（還有一堆會議？），恐怕也沒有太多時間去思考一篇文章要怎樣寫才好。
能不能寫出對讀者有用的文章，除了需要掌握文章內容涉及的技術與 know-how，更重要的是有沒有去思考一篇文章該怎麼寫，才能讓人讀起來舒服、易懂、有學到東西或者解決他們手邊碰到的問題。當然我們不能排除有的人已經是寫手等級，或者對於想要寫的內容早已在心中醞釀多時、胸有成竹，故可下筆如有神，一蹴而就。
簡單來說，關鍵在於：身為作者的你，是否知道怎樣的技術文件才是對多數的目標讀者有幫助？如果寫文件的過程能夠經常考慮這點，並持續改善文件內容，我想已經走在對的道路上。能夠做到這點，自然也就懂得 docs as a product 是一個怎樣的理念。
有關成為 technical writer 的一些個人特質與要件，之後可能再另開一篇筆記來分享個人淺見。
總之，docs as a product 不是把技術文件當成零散筆記、隨意為之，而是經過作者構思與細心整理的文件。作者知道知識傳遞與知識分享的重要性，他／她希望有更多人願意讀這些文件，且信任這些文件，故願意投注長期的心力來持續改善文件的品質，就像持續改善一項產品那樣。
Content first
內容優先，這也相當直觀，文件首重其內容是否有用，自然是內容優先了。強調這點的原因是相對於其他考量來說的，例如：優先考慮文件撰寫工具或文件管理平台是否容易取得、工具是否好用、產生出來的文件是否美觀 fancy 等等。
Content first 的前提是上一節介紹的 docs as a product。因為有些文件並不需要那麼嚴肅認真地對待，例如一些不穩定的知識、臨時筆記、零碎知識等等，我們可能不會大費周章去把它們當成一個產品來發展與維護，於是內容結構如何、是否易讀易懂，也就不需要那麼講究。
那麼，如果要認真去寫正規文件，該如何構思文件的架構呢？
構思文件架構
一旦確定要撰寫正規文件，把文件當成一項產品來認真看待，便需要規劃和構思文件結構與內容。此時，有一個名為 Diátaxis 的文件構思框架可以派上用場。如下圖（取自 diataxis.fr）：
此框架把文件分成四大類：
教學文件：協助讀者學習某一個主題。
How-to 文件：包含完成特定工作或目標的指引。例如「如何建立虛擬機器」、「手把手教你 XYZ」通常屬於此類。
解釋型文件：說明某個概念、名詞、架構等等都是。
參考文件：提供參考資訊，例如 error codes、API reference manual 等等。
構思技術文件該包含哪些內容時，不妨以此框架來規劃文件的架構。
有了大分類之後，可以再進一步思考更細、更具體的文件類型，例如：
Introduction、overview
Tutorials
Use cases and best practices
FAQs
API reference manual
專有名詞（terminology）
產品的 road map
產品的 release notes
聯繫技術支援的管道
提供有關文件內容 feedback 的管道
相關法規與政策
規劃文件內容架構時，若想不到該放哪些東西到文件中，不妨利用上述清單來刺激靈感。
結語
本文提及的概念和方法，都是我贊同且正在使用的，而且我覺得對於從事軟體開發或系統工程方面的 DevOps 與工程師特別合適，因為相對容易上手。比如說，讓 DevOps team 成員學習使用 markdown 來寫文件，碰到的抗拒通常會比一般習慣用 Word 和 Powerpoint 寫文件的人來得低。
然而，也不能預設只有 DevOps 工程師才能使用這套方法來寫文件。理想情況下，撰寫文件的相關配套工具、平台、教學文件，也都應該盡量準備齊全而且容易上手，讓組織中的其他角色（例如 PM、SA）也能參與文件協作、貢獻知識。
最後，最重要的，無論採用何種工具，只要是正規文件，都應該以易讀易懂為目標，而且能讓讀者自行閱讀文件就學會特定知識、或解決特定問題（而不是看了文件感覺一頭霧水還得一直去找人問）。
喔對了，非正規文件當然也可以用上述理念和方法來撰寫，例如部落格就是練習寫文件的一個好方法（儘管有點老派，但還是很棒的方法）。
Keep writing!
延伸閱讀
本文轉貼自 Huanlin's Note
喜欢我的文章吗？
别忘了给点支持与赞赏，让我知道创作的路上有你陪伴。
发布评论…