解決方法:編寫(xiě)面向受眾的文檔
如何解讀一種特定類(lèi)型的文檔取決于個(gè)人在組織中的位置。例如,對(duì)于系統(tǒng)管理員而言,API參考文檔毫無(wú)用處,對(duì)高級(jí)系統(tǒng)管理員也樣。他們不可能花時(shí)間去閱讀API參考文檔,更不用說(shuō)讓他們解釋或使用API參考文檔去改進(jìn)運(yùn)維過(guò)程了。系統(tǒng)管理員需要的是面向系統(tǒng)管理員環(huán)境編寫(xiě)的文檔。這種文檔本身可能會(huì)包含很多來(lái)自API參考文檔的信息,但是這個(gè)文檔不應(yīng)該只羅列函數(shù),還應(yīng)該包含其他一些信息,如API可以支持多少個(gè)請(qǐng)求,它使用什么網(wǎng)絡(luò)協(xié)議,以及它依賴(lài)哪些軟件,等等。這樣才能幫助系統(tǒng)管理員理解如何部署應(yīng)用程序,從而知道應(yīng)在服務(wù)器環(huán)境中部署哪些組件。在這種情況下,我們會(huì)先從API參考文檔開(kāi)始,然后給出面向兩種讀者的兩個(gè)具體的API實(shí)現(xiàn)文檔:運(yùn)維指南和開(kāi)發(fā)指南。
編寫(xiě)面向不同受眾的完整文檔集,讓文檔成為一個(gè)團(tuán)隊(duì)文化的鮮活部分。一定要理解需要使用文檔的受眾,如業(yè)務(wù)用戶(hù)、系統(tǒng)管理員、數(shù)據(jù)庫(kù)管理員、軟件開(kāi)發(fā)人員、網(wǎng)絡(luò)工程師、項(xiàng)目經(jīng)理,等等。對(duì)于業(yè)務(wù)用戶(hù)而言,或許API規(guī)范需要考慮所支持的每種應(yīng)用的開(kāi)銷(xiāo)成本;而對(duì)于網(wǎng)絡(luò)工程師來(lái)說(shuō),則可能需要說(shuō)明應(yīng)用程序使用了哪些協(xié)議。應(yīng)該編寫(xiě)哪一種文檔,并沒(méi)有一種固定模式,而完全取決于業(yè)務(wù)及團(tuán)隊(duì)的需要。
好處:強(qiáng)化不同團(tuán)隊(duì)之間的紐帶
面向不同受眾編寫(xiě)文檔,其結(jié)果必然能夠優(yōu)化人們對(duì)于業(yè)務(wù)雙方的理解,減少誤解和錯(cuò)誤,并且減少雙方的壓力。而且,我們可以在一個(gè)文檔的基礎(chǔ)上編寫(xiě)另一個(gè)文檔。例如,在了解網(wǎng)站建設(shè)應(yīng)用程序及運(yùn)維基礎(chǔ)架構(gòu)(服務(wù)器、網(wǎng)絡(luò)設(shè)備等)的功能與限制之后,我們就可以在維護(hù)、功能規(guī)劃成本及可擴(kuò)展性指標(biāo)上使用這些信息。如果一個(gè)文檔可以利用另一個(gè)文檔,那么編寫(xiě)文檔的時(shí)間就會(huì)大大減少。這種方式不一定適用于所有情況,但是很多時(shí)候都是這樣的。
本文地址:http://www.khwajamoinuddinchishty.com//article/4501.html