博客園里討論編程的文章很多，卻沒有見過誰發(fā)表過文檔撰寫方面的，或者有，是有我不知道呢？但無可否認(rèn)的是，涉及到到文檔方面的極為罕見。這是否與程序員對文檔的編寫不夠重視有關(guān)呢。

作為一名程序員，我也曾經(jīng)犯這樣的錯誤，對于文檔的編寫不夠重視。但是長期地和客戶接觸中，發(fā)現(xiàn)文檔的撰寫極為重要，出色文檔絕對可以為你的軟件錦上添花，同時，可以減少花在客戶身上技術(shù)支持的時間。現(xiàn)在，我就談?wù)剬懳臋n的一些心得。

一份文檔，應(yīng)該是由以下幾部份組成

1、軟件的簡介。這部份內(nèi)容應(yīng)該把軟件的特點給描述清述，讓用戶知道你的軟件都有些什么功能、用途。對他們的工作或者生活有些什么幫助。這部份內(nèi)容，應(yīng)該是簡潔明了，并且描述清楚的。讓用戶能夠在一分鐘之內(nèi)，就能夠作出判斷，這個軟件是不是他們想要的。***能配上軟件的截圖，讓用戶對你的軟件有個直觀的認(rèn)識。

2、使用授權(quán)。這是一個必不可少的部份，你必須清楚的認(rèn)識，你以自己所寫的軟件是擁有版權(quán)的，授權(quán)哪些人，怎么授權(quán)是你權(quán)利。必須要告訴用戶，他們在使用你的軟件有些什么限制。一般來說，***使用常用的協(xié)議，因為我估計，沒有哪個用戶愿意花太多的時間來仔細閱讀你的授權(quán)協(xié)義。

3、快速入門。在這部份內(nèi)容里，你應(yīng)該教會用戶使用你的軟件。時間***限制在三分鐘之內(nèi)。否則用戶很容易會放棄。這部份內(nèi)容的目的是讓用戶進一步了解你的軟件，吸引用戶去積極使用。所以，這部份內(nèi)容要挑最重要，而又最簡單，最能體現(xiàn)你軟件特色的功能。

4、參考。這份內(nèi)容應(yīng)該是越詳細越好。把你的軟件、功能描述得面面具到。這部份內(nèi)容是讓用戶全面掌握軟件的使用。

5、常見問題。在這部份內(nèi)容里，應(yīng)該羅列出用戶最常到的一些問題。對于用戶碰到的問題，能夠迅速找到解決的答案。

6、HOW TO。這部份內(nèi)容應(yīng)該邏了一些常見的任務(wù)，然后一步步地教用戶怎么去使用你的軟件。把這部份內(nèi)容稱為 STEP BY STEP 也可以。這部份內(nèi)容，一部是放在快速入門那里部份里。

以上幾部份就是常見的文檔組成。接著來談?wù)勎臋n的編寫。一份好的文檔，用戶一眼看上去，要有一種賞心悅目的感覺。因此文檔的編寫要注意下面幾個問題：

1、文檔要有索引，也就是目錄。這個非常重要，因為它能迅速幫助用戶定位到他所感興趣的內(nèi)空。

2、排版要美觀。從我個人的經(jīng)驗來說，具體就是大標(biāo)題要居中，多個的小標(biāo)題要有序號。段與段之間的間隔要適中。不能都擠在一塊，否則會影響閱讀。

3、字體大小要清晰易看。簡單點說，就是喵上一眼，就能了解到這個章節(jié)的結(jié)構(gòu)。哪部份是標(biāo)題，哪部份里摘要，哪部份是內(nèi)容，哪部份是示例、哪些是關(guān)鍵字。這些都可能通過字體的大小，粗體，斜體，下劃線這些來體現(xiàn)。另外，還有一個要注意正文內(nèi)容的字體不能過小，否則長時間的閱讀容易讓眼睛疲勞，我一般都是選用5號字體。

大家如果對文檔的編寫感興趣的話，可以到http://esql.codeplex.com 下載 ALinq Dynamic 來看看，它里面包含的一份中文文檔，基本是按照上面所說的去編寫的。

原文鏈接：http://www.cnblogs.com/ansiboy/archive/2013/03/11/2953988.html