雖然編制文檔并不是眾多IT 專業人員選擇職業的真正原因，但是足夠的激情、勤奮工作和注意細節將會使你成為老板的一份更具價值的資產并能夠提升你的履歷。

本文我們介紹了取自 10 Things 博客中的文章《創建軟件文檔的10 項技巧》。該博客主要面向應用開發專業人員，但是項目經理和管理人員也可以從他們的智慧中獲益。

Alan Norton 從事軟件系統開發和相應軟件項目文檔編制工作很多年。我們可以從他的多年從業經驗中獲益。

坦白地講，沒人想寫，沒人想讀或者實際上是不得不作這項工作。我想說的是 軟件開發 中的文檔編制，通常定義為軟件生存期的倒數第二步。雖然編寫文檔可以而且應該出現的 軟件生存期 的任何階段，但是本文我們將集中在文檔編制階段。需要注意的是我們要討論的文檔包括兩部分：終端用戶文檔和系統/內部文檔。

項目生存期

在準備這篇文章而做一些研究時，我找出了Petrocelli/Charter 1976年出版的Anthony Ralston 和 Chester L.Meek編輯的計算機科學百科全書。可以明確地是這是第一版的經典，但是有一些東西是永恒的，其中在文檔詞條關于文檔的描述為：

“文檔是開發和應用基于計算機的系統的重要部分。在一些商業組織，20%到40%的開發工作量用于新系統的文檔編制，其中記錄了新系統是如何工作的以及是如何開發的。”作者K.R.London。

我對于這個定義在今天的正確性感到好奇，如果是真的話，那么為什么媒體沒有給與文檔應該的關注。在項目生存期我們找不到很多關于文檔花費的信息（如 圖A）。我猜測可能是這些花費經常被低估或沒有進行合理的收集。從事工作系統開發的IT專業人員，很多可能會將文檔的實際花費看作是件尷尬的事或者認為這 反映了他們不良的生產率和工作。

對項目生存期文檔階段的重要性的看法，可能依賴于你在IT組織的角色。如果你是經理或 項目 小組組長，那么你會認為文檔對于項目的成功是十分重要的。如果你處于一個非管理職位，那么你會認為編制文檔是件惱人的麻煩事，因為它妨礙了你的實際工作。盡管下文的10項技巧主要面向后一類人員，但是項目經理和管理人員同樣也可以從中獲益。

圖 A

7步項目生存期來源：WikipediA

#1: 如果可能盡量編制圖形文檔

有句古老的格言說是一幅圖勝過千句言，意思是說通過使用圖形表達你的觀點，將會使文檔的長度和復雜性減到最小。系統用戶喜歡使用圖形，圖表，表格和列表進行快速查找參考。

#2 ：給出示例

例子是終端用戶快速掌握他們可能沒有完全理解的概念的最好方式。同時對學習使用新軟件的終端用戶來說，例子還是他們坐下來更容易地處理一項新的挑戰好方式。下面是一個帶有圖片的文檔的例子：

Vista商業、終極和企業版中的先前版本

先前版本是微軟用于存儲一個文件影印的術語。如果你正在編輯一個文檔或任何其它勞動密集型的項目且意外地丟失了部分或全部工作，那么你可以返回到一個先前版本。先前版本可以看作是以自動的方式及時地對以前的文件拍下的快照。

但是首先我們需要配置Vista，以便開啟你想要用來恢復丟失文件的先前版本功能（圖B至圖E）邏輯磁盤/分區。

開啟先前版本

圖 B

選擇開始|控制面板

圖 C

左鍵單擊高級系統設置——如果提示UAC（用戶賬號控制）左鍵單擊繼續。

圖D

左鍵單擊系統保護選項卡

注意：默認情況下，Vista邏輯磁盤/分區已經開啟。在完全清楚這樣做的后果后在改變這個設置。

圖 E

向下滑動滾動條選擇邏輯磁盤

左鍵單擊滾動條并向下滑動只到在邏輯磁盤/分區中找到你要開啟先前版本的那個分區。在本例中的邏輯磁盤名為Documents。左鍵單擊邏輯磁盤名前面的單選按鈕選中。

注意：影印文件的創建基于系統創建恢復點的時間和頻率。根據Vista的幫助文件，典型情況是一天一次。

單擊應用然后單擊確定關閉系統屬性窗口。單擊文件|關閉或單擊控制面板|系統窗口右上部的紅色X按鈕關閉它。

為了恢復一個文件的先前版本，你可以右鍵單擊瀏覽窗口中的文件名然后左鍵單擊恢復先前版本即可。

注意：一旦文件的一個影印被恢復后，就不能用于二次恢復。在下一個系統恢復點創建之前，不能創建另外一個影印文件。這就意味著任何在下一個系統恢復 點保存的文件不能恢復到你前面使用的那個先前版本中去。應該加強練習注意在使用了恢復先前版本選項后直到下一個恢復點發生和另外一個影印文件可以創建后在 保存文件。

#3: 不要指望假設

即使你知道你的目標用戶群，也需要編寫應用文檔以便任何一個具備基礎計算機技能的人都可以閱讀并學會如何正確的使用新系統。可能的情況下，應該提供 一步一步地操作指令。但為了避免混亂，可以考慮將文檔放在附錄中，單獨的章節中或通過超鏈接訪問它們。如果你在編寫文檔，改變一下你的思維方式從而使你可 以站在新系統用戶的角度考慮問題。起初，這可能有點困難，但是只要你注意細節并對將所有特性和功能變成文檔，你就可以創建一個良好的文檔，而不用假定用戶 可以自己領會你沒有包括進去的信息和過程。

不用假定終端用戶能夠理解所有的縮寫詞，這些縮寫詞往往擾亂了IT的美景。在第一次提出一個新的縮寫時，應詳細說明該縮寫代表什么意思。

#4 ：預期可能的問題

在測試系統時，應該盡你所能用各種方法測試你的軟件。如果你的軟件存在明顯的錯誤( 開發人員喜歡稱為錯誤，終端用戶稱它們為漏洞)，那么應該將解決辦法編寫進文檔并提供給用戶和服務臺。這樣不僅可以省去終端用戶的諸多問題還可以省去服務臺大量的額外電話咨詢。

任何生存期較長的系統，對在生存期間不可避免的事件應該編寫成文檔。

當系統或網絡實效時，可以使用什么樣的工作區？

如何從一個嚴重的內存溢出，一個硬盤崩潰或數據庫崩潰中恢復？

一個對于你的系統一無所知的人如何啟動系統并運行它？

你的文檔應該預期這些問題并提供一個詳細的計劃和指令用于系統恢復。

替代你的人知道到哪里找到你的文檔和任何其它購買的供應商的應用文檔嗎？所有這些文檔應該整齊的組織在一起并存放在一個安全容易找到的地方。

預期問題的另一個很好的例子是Y2K千年蟲問題及其解決方法。20世紀90年代后期媒體開始報告由于在合法系統中只用兩位數字存儲年份所以系統和軟 件可能會失效。這個問題被預先考慮到并投入了大力努力在問題出現之前解決它。開發的軟件對2000年1月1日之前的年份被設計成并確保與Y2K相兼容的年 份表示方式。結果取得了顯著成功。除了少部分報告的問題外，對IT社區來說，2000年的新年是一個歡樂的時刻并不是一個大災難日。盡管我們派出大量專門 人員隨時待命以應對突發的問題。

在你的文檔中也可以用同樣的方法預期可能出現的問題。同時千年蟲問題還顯示了應該不斷的對文檔進行更新。修改系統/內部文檔來說明軟件和系統的Y2K兼容性或不兼容性。對于以前的合法系統，找到工作區并將之文檔化。

#5 ：測試你的文檔

坐下來查看一遍你的說明。如果你的文檔是在介紹如何構建一個服務器，一個網絡或任何其它IT系統，那么最好從一個空白的地方起步，一切從頭開始構建。毫無疑問，你肯定會發現遺漏了某些東西或者其中一些操作說明不是很清楚。

在發布之前，與一些沒有通知過但很忠實同事共同檢查文檔以獲得他們的反饋信息。讓他們測試你的文檔。

當你與一個人一起坐下來第一次檢查你得軟件和文檔時，你將會對你所學到的東西感到吃驚。大量對你來說是很明顯的軟件特性但對另外一些誠實且樂意與你共同工作的人可能并不明顯。仔細的觀察你得實驗者在操作軟件時做了些什么，尋求反饋信息并做好記錄。

我還記得在我的一個項目測試期間得到反饋信息，是用電子郵件寫給我的，因此我可以逐條閱讀。我頭腦中第一個想法是“這樣做要花多少時間？”你可能會 將這些評論看作是批評性的或針對個人的。不要在犯這樣的錯誤了。現在回頭想想，我本應該實現有益的批評者提到的更多被遺漏的特性。

利用這個機會可以對你得項目進行最后的完善。編制文檔過程中的反饋信息可以幫助使得整個項目更加成功。

我正在為Foxconn 975X7AB-8EKRS2H主板寫評論，碰巧在使用手冊中發現兩處錯誤。我并不是第一個評論Foxconn板的人。Foxconn忽略了錯誤且所有其它評論人員也都忽略了錯誤。其中一個錯誤絕非是微不足道的。

手冊中顯示清除CMOS跳線設置的正確位置的圖表是錯誤的。我知道是因為當我們翻轉主板以驗證散熱片的位置是否正確時，跳線就跌落了。我根據手冊中的說明將跳線放回原處，但計算機的加電自檢功能失效。在仔細查看了主板上的微型圖表后，我發現了錯誤并修改了放錯的跳線。

那個時候我正和一位來自Foxconn公司的技術人員合作共事，這位技術人員很友好的回答了我的問題，然后我告訴他出現的錯誤。像這樣的文檔錯誤很容易被忽略，但可能給生產商帶來潛在的巨大代價。要不是在翻轉主板時跳線很松以至于脫落下來，我也不會發現這個錯誤。

#6 ：將你的工作盡量人性化

你曾經閱讀過多少次用戶手冊？又有多少次想過在另一方編制手冊的真實一個生活中的人嗎？——或者用戶手冊是由計算機自動編制的嗎？雖然你不是在創作一部豐富多彩的小說，但是盡量使文檔人性化一些，使其具有一些你得個性，這樣讀者在閱讀手冊時會感覺更舒服一些。

#7 ：使用新技術

即使所有工作都是正確的，文檔編制的代價也是很高的。為了幫助開發更為有效的文檔、節省開發費用將會不斷推出各種新技術。我們可以將這些新技術看作降低文檔編制過程的時間和費用的好機會。

作為項目小組的一部分，編制文檔尤其困難。你的文檔需要同其他小組成員共享并添加到他們的文檔中去。通常還有每天進行修改。軟件應該考慮到這一點，這不僅有助于確保提供一個標準化的終端產品，還有助于培養小組成員之間分享觀點和知識的習慣。

當我在CSC（計算機科學公司）公司工作時，我曾經利用混合結果對微軟的Agent和文本到語言技術作過實驗。我始終認為它為新用戶了解我的系統的 一些特性提供了一個精彩的方法。一些人可能還記得Word 97中小紙夾字符的閃光效果是多么令人討厭，這個比那個更令人討厭。

使用Agent，你可以將你的的字符在屏幕上移動，指向一個下拉框，編程的方式打開下拉列表框并可以告訴你提供的選項有哪些。我為我的軟件創建了一個向導，讓學舌著Peedy指向列表框，輸入文本向列表框，改變屏幕，引導終端用戶在數據庫中創建記錄的整個過程。

使用Agent使我避免了編寫大量冗長乏味的文檔，其中將會詳細地介紹創建，保存和修改新紀錄的操作步驟。它可以使我得工作更具創造性，讓我以一種 積極和有益的方式參與文檔編制工作。創造性是大多數開發人員具備的素質而且是使他們成功的一個關鍵因素。在開發文檔時，可以而且應該考慮創造性，這取決于 你所在公司的標準和期望。

我收到的關于我的微軟Agent實驗的唯一的反饋信息是有些人有太多的空閑時間而且沒有認真看待這件事，至少有一部分是因為滑稽的外觀字符。構建它 不需要大量額外的工作，但是它確實要求我們學習一些新的編碼技術。我們部門的某個人接受培訓是件愉快的事情，我可以告訴他們使用向導導游。可能微軟很有超 前意識并有大量令人尊敬的高級人才，這類技術總有一天仍將成為主流技術。

最近，作為50年結婚紀念日的禮物，我為父親構建了一臺計算機。我編制了一些標記為重要的PC說明請閱讀字樣的說明文檔并留在桌子上面一個快捷操作 方法。同時我還創建了一個音頻文件介紹了計算機的特性和使用說明。我問他是否看過我寫的使用說明，但是它告訴我他按照計算機使用音頻向導進行操作。

這是一些替代文檔的例子。以筆者的拙見，在今天的公司環境下，編制文檔的新方法遠未充分利用而且低估了新方法的簡單性和潛在的影響。

盡管編者文檔很麻煩，但仍舊需要開發文檔化的軟件包，不過已經出現了 大量有用的文檔編制工具 ，它們被設計用于完成特定的文檔編制任務。

#8 ：如果可能的話，盡量自己完成文檔編制

編制文檔的最佳人員就是開發者自己。畢竟，還有誰比系統開發者更理解系統功能？

如果你是一名系統開發員，那么你也可能是一名高明的程序設計員。但是僅僅在程序員面前提到文檔這個詞，他就會作出“你開玩笑吧”的樣子。如果強制的 話，程序員也會完成他們的文檔編制工作，或者至少會試圖編制一些將會轉給文檔人員的資料文件。我知道，我見過很多這種情況，甚至我自己也有這種錯誤。

這是一個現實的尷尬，因為一個擁有良好的編制文檔能力的程序員是公司十分有價值的資產。如果是另外一個人為你得項目編制的文檔，那么在性能評價時你的項目經理會記住什么？我猜肯定不是你應該得到晉升，加薪或得到獎金。

雖然不是很有趣，但是當正確的編制時，文檔還是很有益的。不僅可以使你提供給客戶一個更好的完整項目，而且還可以減少將來你不得不提供的支持時間。同時還可以減少服務中心的支持次數和維護時間。

當我在CSC工作時，我有機會作為項目負責人設計和開發我們的全球報告系統和基礎設施。我能夠直接看到文檔的另一方面。我們小組中有一位很好的程序 員，他負責的工作是水晶報表API設計和定制功能開發。很明顯對我來說他的知識是唯一的，所以需要與其他小組成員分享，有什么更好的方式讓大家分享他的知 識而不僅僅是將他的工作文檔化？我沒有完全成功地使他向大家解釋他的工作達到其他人可以按照他的方法自己做的地步。不過，他的確列出并解釋了函數名稱，如 何使用它們，它們如何工作以及它們是如何實現的，這對于其他小組成員是很有幫助的。

在編碼領域像存在一條不成文的規定，程序員的編程能力與他所承擔的文檔編制工作量成反比。

在我的職業生涯中給于我的第二大稱贊是，當我為我們的全球技術支持小組作報告時，我不得不創建并提供一份關于如何創建報告服務器的文檔。其中我們的 一位數據庫管理員是一位來自英國的小伙子，他也出席了報告會。在看了我寫的如何創建一個報告服務器的文檔后，他解釋并評價說文檔寫的太好了，按照我的文檔 說明他完全自己能夠構建一個報告服務器。諸如此類的語言使我的辛苦工作變得很有價值。對主要的項目工作來講，這并不值得贊美——但是對文檔來說這是值得 的。

#9 ：協調終端用戶文檔與內部/ 系統文檔的編制

如果同時編寫用戶文檔和系統文檔，這將會節省你的時間。你可以在兩者之間共享一些信息并減少信息遺漏。即使你不想這么做或者這兩個文檔之間不適宜分享信息，你也可以從其中的一個文檔的主題中獲益，這將有助于你在另一個文檔中包含補充的文檔。

#10 ：遵循部門或公司的文檔標準

創建和遵循標準格式和指南。這將有助于確保避免丟失重要信息并便于系統用戶閱讀。

在洛杉磯休斯飛機公司工作時，有一次我曾經和一位專業的文檔專家共同為我的系統編寫文檔，結果相當成功。格式是遵循部門標準而且結果比我希望的要 好。達到這種結果需要大量時間和精力。文檔專家需要訪問我的測試系統并與我接觸，因此我可以回答他的問題。這樣做的代價是昂貴的，并不是所有公司都有這樣 的資源來收集專業文檔，但是如果系統開發人員能夠核實終端產品的重要信息沒有被曲解或者遺漏，那么結果也可以卓越。

十分幸運，我曾經有一位工程師，他在編寫文檔方面也很出色。他能夠理解設計、開發的系統是做什么的，通過實際使用系統來發現它是如何工作的，然后填寫說明文檔中的空格。你可能沒有這么幸運。

在今天這個全球市場，銷售和支持的時代，文檔也應該遵循國家或地區標準。我經常需要重復讀好多遍中國制造的電子齒輪的使用手冊，因為它實在太難翻譯 了。它是用中式英文寫的，對于一些句子我不得不停下來，然后試著理解它的意思。我通常只是像斯庫比-杜那樣想一想，然后移到手冊的其它部分。

用英語寫成的文檔是否能夠方便中國人學習理解呢？我想文檔中的英語對說漢語的人來說可能會跟聽英語的感覺一樣。為了使得文檔更易于理解，應該找到并用一位專業的翻譯人員來翻譯，從而可以避免翻譯中遺漏重要信息。

我還應該說得更明白一點。你的文檔應該避免拼寫錯誤和語法錯誤。記住使用拼寫檢查程序來查找錯誤。每當我重讀文檔時，我總是吃驚于怎么會出現如此多明顯的拼寫錯誤和簡單疏漏。

文檔編寫人員

如果我還沒有使你信服編寫良好的文檔對你和你的老板都十分有益的話，那么下面的事實將會讓你感到舒服些——編寫良好的文檔決不僅僅是仆人的任務。當 將你的工作文檔化時，你也就是一名文檔編寫人員。希望這些技巧將會有助于你避免出現這些浪費時間和破壞性的問題，對于你和你們的服務中心的技術人員來數， 這些問題是常見的。

作者按：

這是我第一次正式發表文章。在這里我要感謝Sonja Thompson和Mark Kaelin給我這個機會讓我同大家分享我的想法。我不確定為什么Mark決定給我這個機會來討論這個令人畏縮的主題作為我的第一篇文章。可能是如他指出 的如果我能寫一篇關于文檔的令人感興趣的文章的話，我就可以寫幾乎是任何東西了！我很高興他這樣說。我對他和TechRepubic的感謝難以用語言來表 達。

一個無名的讀者現在已經成為一名無名的作者。

額外參考：

“…有關文檔的四個最重要的屬性是它的內容，維護，可獲得和使用例子。”第58頁

http://www.site.uottawa.ca/~tcl/gradtheses/aforward/aforward_thesis.doc

文檔的重要性

http://searchsmb.techtarget.com/originalContent/0,289142,sid44_gci1251087,00.html

責任編輯：德東

10技巧創建軟件開發文檔