編寫文檔就是對相關內容進行編輯、修改和調整。如果資金和時間都比較充足可以由專門的人員來做。能做出高品質的文檔。
基本介紹
- 中文名：文檔編寫
- 外文名：Documentation
- 定義：文檔編寫是指可以進行編輯與修改
人員配備,工具選擇,注意事項,
人員配備
1.文檔編寫者：實際編寫文檔內容的人。如果資金和時間都比較充足可以由專門的人員來做。能做出高品質的文檔。但是這種情況在廣大的中小項目中比較少。多種情況下，編寫文檔的人會是程式的設計或開發人員。他們熟悉項目，省去了培訓的成本，但是工作性質的不同決定了他們一開始寫出的文檔品質相當的不高。對項目的過度熟悉讓他們潛意識地覺得文檔沒有什麼內容好寫。
2.文檔審查：負責文檔的內容正確性，用語準確、簡潔。說白了就是英語文檔的語法、辭彙檢查。同時也許要負責文檔基本樣式的定製和進度的安排。不要以為英文文檔才需要，就是中文文檔，不同人寫出來的風格也不一樣。但是文檔是要有統一的風格的，所以一定有人專門的人負責這個廣義的風格。這個人最好有一定的計算機使用功底，不是隨便一個英語好的就OK的。
3.技術支持：一般是兼職，要做的事實在不多，但是這部分的工作也是很重要的。主要包括如下的幾個方面：
(1)負責HTML文檔的模版。
(2)CSS的編寫和維護：沒有一個共享的CSS維護頁面的樣式可是很不專業的表現。
(3)CHM項目的維護：要有完整的目錄和索引。
(4)程式與CHM的整合：當用戶在程式的一個地方按F1時，要能打開CHM的相關主題頁。
工具選擇
1. HTML編輯工具：就是用什麼軟體寫文檔的問題。一直都是做.NET開發，所以選擇HTML編輯大都在MS陣營里選。主要有以下幾種HTML編輯器。
(1)Dreamweaver：做WEB開發的老大級產品。
(2)Visual Studio：如果用VS開發程式，那么寫文檔直接用VS打開HTML就可以了。
(3)Expression Web：Expression套裝的重要組件，由FrontPage發展而來。良好的代碼自動完成功能。Design界面等和VS的實在是很像，感覺很可能用了同一個核心。一個缺點就是不會監視檔案的外部更改。這個東西是要買的，不買的話只有一個多月的試用期，如果不想花錢，而文檔計畫又要在一個月之內完成。用這個是很合適的。
(4)各種Office：比如Microsoft Office、Open Office等都可以用來編寫HTML。也是最差之選。有了模版之後，用記事本也比這個強。生成的HTML有大量垃圾代碼，沒有CSS，多人編寫時不便於merge。不到萬不得已絕對不要用這個東西寫HTML文檔。用這個東西好處就是方便領導Review。加批註比較方便。而Open Office的優點就是免費。
2.檔案管理平台：文檔檔案多了，寫文檔的人和審閱檔案的人一起工作難免會有同步檔案的問題。為了解決這個問題，可以用CVS，Source Safe，Perforce之類的源檔案管理軟體幫助維護文檔檔案。檔案多，人也多的時候，這一點非常重要。
注意事項
1.由於是HTML文檔，其中的Hyperlink是依賴於檔案名稱的（程式設計師都知道，不過審閱文檔的可不一定，一高興把檔案名稱改了不是玩的）。所以輕易不要改檔案名稱。有哪些文檔，都叫什麼，最好寫寫之前確定下來。
2.如果使用HTML Help Workshop生成CHM，檔案名稱不要有’&’等字元。不然會讓連結失效。（發現有些MS軟體的CHM文檔是用GUID當檔案名稱，感覺很不好維護，不知這個HTML是不是從別的檔案生成的。）
3.每次開始寫一種類型文檔之前一定要有一個專門的會議確定要寫什麼，怎么寫，詳細到什麼程式，以及文檔的措辭，圖片的選取等重要問題。如果時間充足，很有必要寫一個文檔的文檔來進行規範化。不要因為所謂的時間緊為由，三言兩語就打發人去開始寫文檔，一個新生寫的文檔一定不是你想要的文檔。結果就是返工。而且即使都是老手，寫得都對，但是一人一個寫法，放一起還是不對。
4.確定版權資訊。一般頁腳都會有著作權聲明。
