更新時(shí)間：2021-06-09 11:00:42作者：admin2
正文如下：
我不知道是不是有人會(huì)將閱讀或書(shū)寫(xiě)技術(shù)文檔當(dāng)做愛(ài)好。雖然很討厭這樣做，但是通常為了解決問(wèn)題或介紹一個(gè)技術(shù)產(chǎn)品，我們不得不去做這些事情。要想寫(xiě)好文檔很難。技術(shù)文檔有幾種形式：基本概覽，高級(jí)概覽，一步一步的演示，自動(dòng)生成的文檔，等等。考慮下不同用戶對(duì)你的文檔的需求情況：不同的需求，不同的技術(shù)，不同的學(xué)習(xí)風(fēng)格。你將會(huì)發(fā)現(xiàn)，沒(méi)有一種格式能同時(shí)適應(yīng)所有人。受眾情況在寫(xiě)項(xiàng)目文檔的時(shí)候，你首先要考慮到的是讀者。最終用戶首先需要的是一份入門(mén)指南。盡管一些技術(shù)概念可能會(huì)提到，但是重點(diǎn)應(yīng)放在用戶界面，而不是后臺(tái)。如果是程序員，他可能會(huì)想得到更多的信息：程序運(yùn)行原理，代碼的實(shí)現(xiàn)，怎樣對(duì)代碼進(jìn)行擴(kuò)展，等等。為部分用戶寫(xiě)的文檔不應(yīng)當(dāng)影響到另一部分用戶的閱讀，你可以考慮寫(xiě)兩份單獨(dú)的文檔，用戶使用手冊(cè)和技術(shù)文檔。幾種不同類(lèi)型的文檔 Jacob Kaplan-Moss在他的怎樣寫(xiě)好文檔的指南中，他提到了三種文檔：教程，專(zhuān)題指南和參考指南。
教程：教程是很重要的，因?yàn)檫@往往是用戶在使用新的工具時(shí)得到的第一印象。我們之前寫(xiě)到過(guò)，有許多不同的工具可以幫你寫(xiě)好教程。如果你想寫(xiě)的話，Kaplan-Moss建議你寫(xiě)得簡(jiǎn)單快速一些，但是不要太簡(jiǎn)單了，可以做一個(gè)演示，為每一步驟添加相關(guān)的截圖。專(zhuān)題指南：Kaplan-Moss說(shuō)這是文檔的主要內(nèi)容。雖然教程提供了一個(gè)高層次的概念，但是專(zhuān)題指南可以讓感興趣的人深入學(xué)習(xí)，內(nèi)容一定要詳盡。Kaplan-Moss提到，一般來(lái)說(shuō)，圖書(shū)要?jiǎng)龠^(guò)官方文檔，但是后者的一個(gè)優(yōu)點(diǎn)是隨時(shí)更新。參考指南：參考指南是為那些已經(jīng)入門(mén)但是還需要更多信息的用戶準(zhǔn)備的。為那些已經(jīng)知道怎樣使用API，但是需要查找確切的函數(shù)參數(shù)或詳細(xì)設(shè)置信息的用戶定制的。要指出的是，參考指南是無(wú)法由教程和普通指南替代的。自動(dòng)生成的文檔只能起一個(gè)引導(dǎo)作用，如果沒(méi)有額外的寫(xiě)作，編輯和組織，它是不可能解決大家的問(wèn)題的。雖然這是“技術(shù)寫(xiě)作”，但是這并不意味著你應(yīng)該放棄文采，語(yǔ)法和拼寫(xiě)檢查。至少得檢查一下語(yǔ)法和拼寫(xiě)吧。