更新時間：2021-06-09 10:13:48作者：admin2
任何新技術，新方法的文檔和書記都大致分為兩類。
第一類是官方手冊，是白皮書，對該技術有最權威的解釋權，由技術提出者維護。此類文檔一般只是枯燥的記錄功能條目，其作用等價于字典（沒人會拿著字典從第一頁看到最后一頁看完）。優(yōu)點是給該技術提供了一致的解釋權，該技術對于使用者有根基可循，缺點是相對枯燥不適合用來技術傳播。
第二類是技術使用者根據自己經驗寫的類似于“最佳實踐”的材料，里面融合和作者個人看法，相對比較生動，組織也很吸引人。優(yōu)點是有想法，適合用于技術傳播，缺點是比較主觀，個別觀點未見得準確或者說有偏見。
當兩部分材料結合在一起就能發(fā)揮最大的作用。
下面分享幾點技術文檔寫作建議（中英文），通用于上述兩種。
1. 應盡量避免使用“你”，“We can”，“You should”這樣的稱謂，取而代之應該使用“用戶”，"Users"這種更通用的稱謂。
2. 盡量多使用忽略動作發(fā)出者的被動句子。
3. 在引用代碼和腳本時候應使用特殊字體標出，必要時還原其在開發(fā)環(huán)境中存在時的色彩。
4. 文中特殊名詞應該用黑體或者粗體標識出來，以提醒讀者此處是一個專有名詞，而非寬泛的敘述。
5. 當在文中用中文提出一個行業(yè)名詞時，盡量在后面用英文寫出其原文，讓已知此概念讀者方面對照，并告知不知此概念讀者此概念非你所造而是有出處。
6. 盡量少用“可惜”，"unfortunately"這種帶有主觀情緒的形容詞和副詞。
7. Bullet或者Numeric列條目時，動作要使用原型動詞引導的祈使句，比如 Create a new account.