轉(zhuǎn)自:http://www.cnblogs.com/ansiboy/archive/2013/03/11/2953988.html

博客園里討論編程的文章很多，卻沒(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í)間。現(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é)。

文檔的編寫

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)字體。

4、字號(hào)要統(tǒng)一。就是說(shuō)，標(biāo)題，小標(biāo)題，內(nèi)容等等的字體，在每一個(gè)章節(jié)里，它的大小都是一致的。不能說(shuō)，有些章節(jié)的標(biāo)題是三號(hào)字體，有些章節(jié)的標(biāo)題是四號(hào)字體。

大家如果對(duì)文檔的編寫感興趣的話，可以到http://esql.codeplex.com 下載 ALinq Dynamic 來(lái)看看，它里面包含的一份中文文檔，基本是按照上面所說(shuō)的去編寫的。關(guān)于 ALinq Dynamic 的介紹，你可以在這篇文章找到，《高仿Entity Framework？Linq to SQL也有春天！》?。

如果你覺(jué)得這篇文章對(duì)你有用，或者有所啟發(fā)，請(qǐng)點(diǎn)一下支持。鼓勵(lì)我繼續(xù)寫出更高質(zhì)量的文章。

轉(zhuǎn)載于:https://www.cnblogs.com/silentjesse/archive/2013/03/22/2975015.html

創(chuàng)作挑戰(zhàn)賽新人創(chuàng)作獎(jiǎng)勵(lì)來(lái)咯，堅(jiān)持創(chuàng)作打卡瓜分現(xiàn)金大獎(jiǎng)

總結(jié)

以上是生活随笔為你收集整理的谈谈技术文档的编写的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。