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

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

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

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

2、使用授權(quán)。這是一個(gè)必不可少的部份，你必須清楚的認(rèn)識(shí)，你以自己所寫的軟件是擁有版權(quán)的，授權(quán)哪些人，怎么授權(quán)是你權(quán)利。必須要告訴用戶，他們?cè)谑褂媚愕能浖行┦裁聪拗?。一般?lái)說(shuō)，***使用常用的協(xié)議，因?yàn)槲夜烙?jì)，沒(méi)有哪個(gè)用戶愿意花太多的時(shí)間來(lái)仔細(xì)閱讀你的授權(quán)協(xié)義。

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

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

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

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

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

1、文檔要有索引，也就是目錄。這個(gè)非常重要，因?yàn)樗苎杆賻椭脩舳ㄎ坏剿信d趣的內(nèi)空。

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

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

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

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