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