博客園里討論編程的文章很多，卻沒有見過誰發表過文檔撰寫方面的，或者有，是有我不知道呢？但無可否認的是，涉及到到文檔方面的極為罕見。這是否與程序員對文檔的編寫不夠重視有關呢。
作為一名程序員，我也曾經犯這樣的錯誤，對於文檔的編寫不夠重視。但是長期地和客戶接觸中，發現文檔的撰寫極為重要，出色文檔絕對可以為你的軟件錦上添花，同時，可以減少花在客戶身上技術支持的時間。現在，我就談談寫文檔的一些心得。一份文檔，應該是由以下幾部份組成
文檔的組成
1、軟件的簡介。這部份內容應該把軟件的特點給描述清楚，讓用戶知道你的軟件都有些什么功能、用途。對他們的工作或者生活有些什么幫助。這部份內容，應該是簡潔明了，並且描述清楚的。讓用戶能夠在一分鍾之內，就能夠作出判斷，這個軟件是不是他們想要的。最好能配上軟件的截圖，讓用戶對你的軟件有個直觀的認識。
2、使用授權。這是一個必不可少的部份，你必須清楚的認識，你以自己所寫的軟件是擁有版權的，授權哪些人，怎么授權是你權利。必須要告訴用戶，他們在使用你的軟件有些什么限制。一般來說，最好使用常用的協議，因為我估計，沒有哪個用戶願意花太多的時間來仔細閱讀你的授權協義。
3、快速入門。在這部份內容里，你應該教會用戶使用你的軟件。時間最好限制在三分鍾之內。否則用戶很容易會放棄。這部份內容的目的是讓用戶進一步了解你的軟件，吸引用戶去積極使用。所以，這部份內容要挑最重要，而又最簡單，最能體現你軟件特色的功能。
4、參考。這份內容應該是越詳細越好。把你的軟件、功能描述得面面俱到。這部份內容是讓用戶全面掌握軟件的使用。
5、常見問題。在這部份內容里，應該羅列出用戶最常到的一些問題。對於用戶碰到的問題，能夠迅速找到解決的答案。
6、HOW TO。這部份內容應該邏列一些常見的任務，然后一步步地教用戶怎么去使用你的軟件。把這部份內容稱為 STEP BY STEP 也可以。這部份內容，一部是放在快速入門那里部份里。
以上幾部份就是常見的文檔組成。接着來談談文檔的編寫。一份好的文檔，用戶一眼看上去，要有一種賞心悅目的感覺。
文檔的編寫
1、文檔要有索引，也就是目錄。這個非常重要，因為它能迅速幫助用戶定位到他所感興趣的內空。
2、排版要美觀。從我個人的經驗來說，具體就是大標題要居中，多個的小標題要有序號。段與段之間的間隔要適中。不能都擠在一塊，否則會影響閱讀。
3、字體大小要清晰易看。簡單點說，就是喵上一眼，就能了解到這個章節的結構。哪部份是標題，哪部份里摘要，哪部份是內容，哪部份是示例、哪些是關鍵字。這些都可能通過字體的大小，粗體，斜體，下划線這些來體現。另外，還有一個要注意正文內容的字體不能過小，否則長時間的閱讀容易讓眼睛疲勞，我一般都是選用5號字體。
4、字號要統一。就是說，標題，小標題，內容等等的字體，在每一個章節里，它的大小都是一致的。不能說，有些章節的標題是三號字體，有些章節的標題是四號字體。
大家如果對文檔的編寫感興趣的話，可以到http://esql.codeplex.com 下載 ALinq Dynamic 來看看，它里面包含的一份中文文檔，基本是按照上面所說的去編寫的。關於 ALinq Dynamic 的介紹，你可以在這篇文章找到，《高仿Entity Framework？Linq to SQL也有春天！》 。
如果你覺得這篇文章對你有用，或者有所啟發，請點一下支持。鼓勵我繼續寫出更高質量的文章。