一個(gè)組織不可能只有高級軟件工程師或系統管理員，所以，只有基于特定規范的文檔就意味著(zhù)只有高級技術(shù)人員才能閱讀這些文檔。這是一種機能障礙問(wèn)題。當然，這些文檔也是必要和重要的，這已經(jīng)比只有閱讀代碼才能了解應用程序的情況好很多了。然而，這并不是一種完整的文檔戰略與文化。



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