寫程式最討厭的一件事情是什麼？我想大家一定會舉雙手贊成--文件！
文件很多時候不是給程式設計師看的，所以就不能以程式設計師的語言去寫。
這就是傷腦筋的地方！
如果是 API 文件，那麼有很多工具可以使用，如 JavaDoc
量身訂做自己的 JavaDoc 上
量身訂做自己的 JavaDoc 下
配合註解的定義與規範，就可以產生一份極具參考價值的 API 文件。
Visual Source Safe 也可以透過註解中一些特殊的設定，也可以做成一份很有用的說明文件（Sorry 如何製作的文件已經找不到了，現在 .Net 環境則改以 Team Fundation Server 來取代 Visual Source Safe 了）
其實系統設計文件，上述的 API 文件製作，或者將每一個單元開發以 Blog 的方式撰寫，都是蠻好的一種方式。
最常在專案中看到的是使用手冊與操作手冊。這兩者有和區別？使用手冊是給使用系統的使用者看的，操作手冊則是給資訊人員看的。這部份在軟體技術文件指引手冊中，有很詳細的撰寫說明，可以去下載來參考。
http://210.71.186.144/cgi-bin/big5/cisa/aa02
以我們公司使用的 ERP 系統（鼎新 Tiptop），我想很多人對他詬病很多（大多數不是對系統本身，因為大部分都跟原始系統差很大了，而是對該公司的服務...XD），但是就系統文件的角度來說，他可是蠻有規劃的（但命名方式就很可議）。
首先，路徑的定義明確，每一個系統模組對應一個程式路徑，每一個路徑底下都分為程式、畫面、Schema、help等目錄，他的畫面與 Schema 就頗具參考價值。程式開發完成的同時，相關的文件也就因應產生。雖然我不是負責 ERP 的開發，但是開發一些外部程式，少了這些文件就完全無法運作。更重要的是，他有固定的命名方式與規則。熟悉了自然就能掌握。
當然，這是屬於 Informix 4GL 的特性，但是如果我們開發程式能夠參考以上的作法，事實上，真能幫我們做好文件，提供很有用的資訊。
我個人是崇尚「自動化產生文件」那一派的
所以只要我看到用Word做的漂漂亮亮的
系統文件或是測試報告
我都會覺得文件很不實在，甚至是假的，
但偏偏就是有人喜愛這一套
就連最基本的Database schema
也有更誇張的說法
「文件寫好的同時，就是文件失效的時間」
(因為schema又改了，而文件卻沒跟著改)
最理想的狀況是：文件有專用的wiki跟wiki範本可以用，有自動化流程，做完單元跟整合測試報表自動上傳，JavaDoc自動做出API文件等等啦。而且透過持續整合來驅動。所有文件都用html格式的話，容易做自動化了。DB Schema有線上工具可以用來做設計，設計結果可以直接更新到DB跟文件，並且有Plugin可以直接生成model的程式...
所有文件都是word，那真是惡夢一場...
沒錯
而我現在天天都活在惡夢中....Orz
沒錯
很多單位要求文件都要美美的，厚厚的
可以擺在桌上裝飾的...XD
其實厚厚的文件拿來蓋泡麵碗最好用了....(誤)
我還碰過這種的...
我問了驗收單位一個白癡問題：「文件大概要做到什麼程度才OK？」
驗收單位：「把每一份文件印出來然後裝訂，站著放，如果不會倒就差不多了」
以前做專案，也沒聽說過 CM（Change Management）這種東西
後來有機會參與財金公司的一個專案（應該說是見習），IBM 主導的
除了 Fly in 的 Consultant，以及眾多的本地系統分析的人員，陣仗之大外，還有一個小姑娘，令人很驚訝的是，所有的人對他都畢恭畢敬的，後來打聽才知道他是負責 CM 的，妳想改什麼，都得透過他同意才可以做文件的修改！...XD
小姑娘
NPNT
零昏
iThome鐵人賽
看影片追技術