網頁設計前端開發的文檔

　　前端開發的文檔相信大多數情況下都沒有後端的服務描述詳細，而大多數測試也僅僅在黑盒測試，所以很多情況下對這片文檔的描述都廖廖無幾。

　　前端文檔缺失的原因

　　前端開發的文檔相信大多數情況下都沒有後端的服務描述詳細，而大多數測試也僅僅在黑盒測試，所以很多情況下對這片文檔的描述都廖廖無幾。

　　* 前端開發的代碼分散——沒有規範化，沒有很好的設計，大多數人仍以業務為主的開發方式。

　　* 測試人員對前端仍然處於黑盒測試，有沒有文檔都不影響到他們的測試進程。

　　* 一旦業務定型，用傳統方式的文檔模式，很難複製到前端開發來。——改變了開發方式(從作坊式到規範化)讓人難以適應。

　　嘗試對症下藥

　　對於代碼分散的問題需要從源頭解決。從規範化開始，試點從頭到尾慣穿規範化，強制的約定，使代碼品質提高。

　　網頁設計這一塊需要下大力氣，中間加入設計 review、代碼review等環節。需要注意的是細微性把控，即什麼是必須的，什麼是可選的，什麼是約定的等有共識。

　　* 功能描述——開發前的工作，對編碼者來說必須收集需求。對於使用者來說，能夠知道寫這個代碼的目的是什麼，解決了什麼問題，還有什麼問題沒有解決，或需要改進。

　　* 設計描述——分享你的思想，這很重要，一個成熟的開發人員看開碼的時候很多時候不是看你實現如何如何，而是看你的設計。

　　* API描述——使用者快速上手。介面是代碼的眼睛。命名要嚴謹，網頁設計不能說也可這樣，也可那樣。經驗告訴我們，介面做得不好，歷史原因就會多。

　　* demo/snippets——給使用的人copy/paste沒什麼不好。

　　* 使用指南——例如庫的使用指南等手冊。或者說一個簡單的上手教程

　　文檔該由誰來寫?

　　從理論上看，文檔都應該由編碼者來寫，其實不然。一個軟體的週期，可以分為：開發前，開發時，使用時，測試時，維護時。

　　那麼各時間段上應該有不同的人來參與。縮小些範圍來看的話，應該將

　　* 開發前收集需求由大家參與。實現者收集後存檔到文檔裡。此為開發目的與預期。

　　* 開發時的API描述，設計描述主要由編碼者來實現。

　　* 開發後/維護時的demo及snippets可以由使用者來完善。

　　設計文檔是否能自動化生成

　　代碼注釋(現在一般都用java doc)可以生成介面文檔。

　　以往都必須自己畫設計圖，配上描述。網頁設計那麼理論上這塊也應該可以通過注釋加入設計的描述，通過文檔生成的工具自動生成設計圖。這樣應該方便多了。