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