中文技術文檔的寫作規範
阿新 • • 發佈：2018-02-01
並行處理 lis 都是 title 段落 gpo mail doc pac
很多人說，不知道怎麽寫文檔，都是憑著感覺寫。
網上也很少有資料，教你寫文檔。這已經影響了中文軟件的發展。
英語世界裏，文檔非常受重視，許多公司和組織都有自己的文檔規範，清楚地規定寫作要求，比如微軟、MailChimp、Apple、Yahoo、docker、Struts 等等（維基百科有一份完整的清單）。中文的也有不少，但都不令人滿意，要麽太簡單，要麽不太適用。
我就動手，參考上面的規範，也結合自己的實踐，總結了一份簡單的《中文技術文檔的寫作規範》。
- 標題
- 文本
- 段落
- 數值
- 標點符號
- 章節結構
我希望，這樣可以拋磚引玉，讓更多人重視文檔，進而真正出現大家普遍接受的文檔規範。
下面是關於寫作風格的一個片段。歡迎提交 Issue 和 PR 補充。
=================================
寫作風格
（摘自《中文技術文檔的寫作規範》）
如果使用了被動語態，應考慮更改為主動語態。
錯誤：假如此軟件尚未被安裝，
正確：假如尚未安裝這個軟件，
不使用非正式的語言風格。
錯誤：Lady Gaga 的演唱會真是酷斃了，從沒看過這麽給力的表演！！！
正確：無法參加本次活動，我深感遺憾。
用對"的"、"地"、"得"。
她露出了開心的笑容。
（形容詞＋的＋名詞）
她開心地笑了。
（副詞＋地＋動詞）
她笑得很開心。
（動詞＋得＋副詞）
使用代詞時（比如"其"、"該"、"此"、"這"等詞），必須明確指代的內容，保證只有一個含義。
錯誤：從管理系統可以監視中繼系統和受其直接控制的分配系統。
正確：從管理系統可以監視兩個系統：中繼系統和受中繼系統直接控制的分配系統。
名詞前不要使用過多的形式詞。
錯誤：此設備的使用必須在接受過本公司舉辦的正式的設備培訓的技師的指導下進行。
正確：此設備必須在技師的指導下使用，且指導技師必須接受過由本公司舉辦的正式設備培訓。
句子的長度盡量保持在20個字以內；20～29個字的句子，可以接受；39～39個字的句子，語義必須明確，才能接受；多於40個字的句子，在任何情況下都不能接受。
錯誤：本產品適用於從由一臺服務器進行動作控制的單一節點結構到由多臺服務器進行動作控制的並行處理程序結構等多種體系結構。
正確：本產品適用於多種體系結構。無論是由一臺服務器（單一節點結構），還是由多臺服務器（並行處理結構）進行動作控制，均可以使用本產品。
同樣一個意思，盡量使用肯定句表達，不使用否定句表達。
錯誤：請確認沒有接通裝置的電源。
正確：請確認裝置的電源已關閉。
避免使用雙重否定句。
錯誤：沒有刪除權限的用戶，不能刪除此文件。 正確：用戶必須擁有刪除權限，才能刪除此文件。
原文地址:http://www.ruanyifeng.com/blog/2016/10/document_style_guide.html
中文技術文檔的寫作規範