當(dāng)前位置：首頁 > 嵌入式培訓(xùn) > 嵌入式學(xué)習(xí) > 講師博文 > 如何寫文檔
如何寫文檔
時(shí)間：2018-09-20 來源：未知
文檔的反復(fù)是很正常的。不僅如此，不得不承認(rèn)寫文檔和看文檔是一件非常讓人反感的事情，但是這件事情的重要性甚至超過了算法的研究本身，希望大家能夠引起重視。在大型的項(xiàng)目管理體系中，文檔的工作要占到70％的時(shí)間。當(dāng)然，多數(shù)情況下我們開發(fā)的文檔只是文檔體系中的一小部分。
開發(fā)人員在寫文檔的時(shí)候往往會(huì)略去一些自己認(rèn)為“順利成章”的事情，而這些事情中的很多往往會(huì)令看文檔的人感到困惑，這是一切文檔工作失誤的根本原因。所以，要掌握“從讀者的角度”去寫文檔的方法。我始終認(rèn)為，文檔的格式雖然重要，但是把事情本身說清楚才是文檔的目的，所以目前不對文檔的格式做具體的要求。但是基本的幾件事情要作為文檔開發(fā)過程中的基本原則提出：
1）參考文獻(xiàn)：應(yīng)該盡可能多地，不遺漏地給出參考文獻(xiàn)，但這并不等于參考文獻(xiàn)中論述過的內(nèi)容就可以在文檔中省略。一般地，我們的原則是，對于參考文獻(xiàn)提到的部分給出簡明但是完整（二者相較，完整更為重要）的論述，然后在后附上參考文獻(xiàn)。更進(jìn)一步，參考文獻(xiàn)應(yīng)當(dāng)打包附在文檔的載體上，因?yàn)橥檎疫@些參考文獻(xiàn)有時(shí)是很困難的。
2）圖表和公式：圖和公式作為“把事情 本身說清楚”的重要手段，應(yīng)當(dāng)大限度地為這個(gè)目的而服務(wù)，所以，和這個(gè)目的無關(guān)的東西應(yīng)當(dāng)盡可能地去掉，從而使讀者可以一目了然。對圖來說，應(yīng)當(dāng)為其目的專門繪制，而不是隨便抓來一副包羅萬象的圖。對公式來說，應(yīng)當(dāng)針對要說明的內(nèi)容的特點(diǎn)給出關(guān)鍵的公式，大段的公式推導(dǎo)應(yīng)當(dāng)作為附錄。所有的繪圖好能夠 把繪圖的原始文件打包附在文檔的載體上，以便后來人進(jìn)行修改。（Visio繪制的圖在Word里可以直接編輯，但是往往就會(huì)出問題，所以也要附上原圖）。
3） 文檔的論述順序：把所有的事情都說清楚，只是文檔的第一步。更為重要的目的是讓讀者能夠通過這份文檔了解設(shè)計(jì)。為了方便讀者，一個(gè)很重要的原則就是讓讀者可以“順序”地閱讀文檔。讀者在閱讀文檔的時(shí)候，很反感的一件事情就是要把文檔前前后后翻來翻去。我們應(yīng)當(dāng)從文檔的段落安排和論述風(fēng)格上做到這一點(diǎn)，如果有需要讀者“前前后后翻來翻去”的地方，一定要用醒目的方式注明。這一點(diǎn)不僅在文檔的撰寫工作中是重要的，甚至在程序的書寫中也是重要的。
4） 寫文檔所采用的語言：應(yīng)當(dāng)首先采用自己熟悉的語言，然后相應(yīng)地翻譯為英文。在文檔工作的實(shí)踐中發(fā)現(xiàn)，如果一上來就采用自己不熟悉的語言，文檔的開發(fā)人員往往會(huì)自覺或不自覺地“遺漏”掉一些論述起來比較復(fù)雜的內(nèi)容。而審查文檔的人也幾乎不會(huì)針對于這些提出異議。這是非常危險(xiǎn)的，為項(xiàng)目日后的維護(hù)和升級埋下了失敗的種子。這個(gè)問題上，我們寧可喪失時(shí)間，也不愿意喪失一篇完整并且準(zhǔn)確的文檔。
