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