# Chapter?2.?起步 有關自由軟件是如何發起的經典模型是由Eric Raymond提出的，在一篇今天已廣為人知的有關開源開發的論文*《大教堂和集市》*中，他寫道： > *每一個好的軟件都始于撓到一個開發者的癢癢處。* > （來自**[http://www.catb.org/~esr/writings/cathedral-bazaar/](http://www.catb.org/~esr/writings/cathedral-bazaar/)**） 注意Raymond并沒有說只有當某些開發人員心里癢癢之后才會導致一個開源項目的誕生。相反，他是說只有當程序員對解決某個問題產生了個人興趣之后，才能產生優秀的軟件；這一點同自由軟件的聯系在于，大部分自由軟件項目的最初動機都是始于一個人的癢癢處。 這仍然是大部分項目的動因，但自從1997年Raymond寫下這些話之后這種現象正在慢慢減少。今天我們有了一些組織—包括盈利性的大企業—從零開始大型的，集中式管理的開源項目。單個的程序員為了解決一個個人問題敲出一些代碼而最后意識到可以有更廣泛地應用的例子仍然是許多新自由軟件的源頭，但不再是唯一的故事。 然而Raymond的觀點仍然是真知灼見。關鍵在于軟件的生產者對它的成功有直接的興趣，因為是自己用。如果軟件沒能達到期望的目標，那些編寫它的個人或是組織會在日常工作中感到不滿。例如，OpenAdapter項目（[http://www.openadapter.org/](http://www.openadapter.org/)），這是一個由德累斯頓·克萊沃特投資銀行（investmentbank Dresdner Kleinwort Wasserstein）發起的一個用于集成不同財經信息系統的開源框架，就很難說是始于哪個程序員的個人癢癢處。它始于一個組織的癢癢處。這些癢癢處直接來自這個組織和他們的合伙人的經驗，因此如果這個項目沒能減輕這些癢癢癥，他們立刻能夠感覺到。這種情形產出了優秀的軟件，因為形成了一個良性的循環。程序不是為了賣給其他人而編寫的，不是為解決*他人的*問題。它是為解決某個*自己的*問題而編寫的，之后再同其他的人分享，足可以把問題想像成疾病，而程序是分發的藥物，用來徹底地消滅傳染病。 本章是關于如何將一個自由軟件項目介紹給全世界，但是其中的很多建議聽起來會很像一個衛生組織在分發藥物。兩者的目標的確非常相似：你要弄清楚藥品的作用，把它發放到需要的人手中，并確保那些人知道如何使用它。但對一個軟件，你還需要誘使那些接受者加入研究計劃來改進“藥物”。 自由軟件的發布是一項雙重任務。軟件既要滿足使用者，也要滿足開發者。這兩種需求不一定是沖突的，但是會為項目初期的展示增加復雜度。其中有些信息對兩者都有用，有些只是對其中一類有用。對兩種信息都應該依照展示的比例原則：描述的詳細程度應該同讀者在該階段所應該花費的時間和努力程度相對應。更多的努力應該帶來更多的回報。當這種關系發生偏差時，人們有可能很快失去信任并且停止投入精力。 這一點的必然結果就是*形象*的重要性。程序員們對這一點總是嗤之以鼻。對本質超越形式的熱愛成了他們職業自豪感的一部分。所以毫不意外，許多程序員表現出對營銷和公關工作的厭惡，同樣，職業圖形設計師往往也對程序員們的產品感到驚恐萬狀。 這是一個遺憾，因為有時候形式*就是*本質，并且項目的展示就是這種情形之一。例如，瀏覽網頁的人對一個項目的第一觀感就是來自網站的外觀。這種觀感的形成要早于任何一種實際的內容之前—包括文字和鏈接。不管這看起來多么不公平，人們無法不形成一個即時的第一印象。網站的形象向讀者傳遞了一個信號，即網站的展示是否經過了精心安排。人類對檢測心思的投入有著極為敏銳的感覺。我們中的大多數人都能在一瞥間看出一個網站是隨便拉起來的還是經過認真思考的。這是你的項目展現出信息的第一步，它所建立起來的印象將對整個項目的后續部分施加影響。 因此，盡管本章的大部分篇幅談論的是你應該用什么樣的內容開始你的項目，但別忘了外觀和感覺同樣重要。因為項目的網站同時為使用者和開發者兩類人服務的，相應的投入也要透明和有針對性。雖然這不是一本討論網頁設計的專著，但是當網站是為多種類型的讀者服務時，有一條重要原則是值得一提的，在點擊一個鏈接之前用戶應該對它的去處有一個大概的了解。例如，當看到“用戶文檔”的*鏈接*時，明顯應該是鏈接到用戶文檔，而不是開發者文檔。運作一個項目一方面是為了提供信息，但同時也是提供舒適。當用戶和開發者們正在猶豫要不要加入時，你應該在預期的地方用一套肯定性的標準來使他們安心。它表明項目有統一的管理，已經預估到了人們可能提出的問題，并且致力于在只花費提問者最少的精力的前提下來解答這些問題。通過顯現這種充分準備的氛圍，該項目發出了一個信息：“如果加入，你的時間不會被白白浪費，”而這正是人們想聽到的。 ### 但首先環顧四周 開始一個開源項目之前，給你一個重要的告誡： 一定要找找看是否有一個現存的項目已經做了你想做的。有很大的幾率有人早于你已經解決了你想解決的問題。如果他們已經解決了它，并且在一個自由許可證下發布了他們的代碼，那今天你就沒有必要重新發明輪子了。當然有例外：如果是為了練習才開始一個項目，那現有的代碼對你沒用；或者你腦中的計劃非常特別，你肯定不會有其他人有同樣的想法，那你也不妨試試看。但總的來說沒有理由不先看一看，而收獲總是很大。如果常見的互聯網搜索引擎發現不了什么，試試在[http://freshmeat.net/](http://freshmeat.net/)（一個開源項目的新聞站點，有關它的更多介紹將在后面提到）和[http://www.sourceforge.net/](http://www.sourceforge.net/)上找找看，同時自由軟件基金會有一個自由軟件的目錄在[http://directory.fsf.org/](http://directory.fsf.org/)。 即使你找不到跟你的想法一模一樣的項目，你也許能找到十分接近的，然后加入這個項目為它增加功能比你自己從零開始一個項目要更有意義。 # 從你所擁有的開始 你環顧了四周，沒找到真正適合你的軟件，因而決定開始一個新的項目。 現在應該做什么呢？ 開始一個自由軟件最難的部分是將個體的設想轉化傳達給公眾。你或是你的團體也許對要做的事情已經十分明了，但是將這一目標清楚地傳達給世界還需要付出一番努力。然而，那是必須花時間做的事情。你和其他的創建人必須決定你們項目的作用—也就是說，劃定項目的范圍，做什么，*不做什么*—然后撰寫一份項目任務陳述。這部分通常不太難，但有時候能暴露出一些有關項目本質的臆想，甚至于分歧，那也沒關系，現在解決這些問題總比拖到以后好。下一步就是將項目打包展示給公眾， 而那純粹是單調乏味的工作。 之所以這樣說是因為打包的工作就是把大家都已經知道的東西組織和編輯成文件—這里所說的“大家”指的是到目前為止參與項目工作的人。因此，對于那些做這項工作的人來說，沒有什么立竿見影的好處。他們并不需要一個`README`來了解整個項目的概況，也不需要一個設計文件或是用戶手冊。他們不需要仔細排列好的，與非正式而又普遍采用的軟件源碼發布方式相一致的代碼樹形圖。對他們來說，無論代碼怎么安排都沒問題，因為他們已經對此十分熟悉，只要源碼能夠運行，他們就知道怎么用。甚至于，項目最根本的設計設想沒有做成文件對他們來說也是無關緊要的；因為他們對那一方面也很熟悉了。 然而，新參與的人需要這些東西。好在他們并不是在一開始就需要全部的資料。在一個項目公之于眾之前，你不必提供每一個有關的細節。在一個理想的世界里，每一個新的開源軟件項目在開始的時候就具備了一個詳細的設計文件，一套完整的用戶手冊（對已經計劃好但還未實施的特性有特別的標識），漂亮地而又可移植地打好了包的代碼，并且還可以在任何電腦系統平臺上運行等等。然而在現實當中，做好上述各項工作是非常耗費時間的，可是一旦項目啟動之后，這些工作可以指望一些自愿人員協助完成。 重要的*是*必須做好展示這一步，以便新的參與者能夠順利通過開始時因對項目不熟悉而造成的障礙。設想自舉過程中的第一步，就是將項目啟動所需的能耗降到最低點。我聽說過人們用*切入能耗*這個詞來形容這一開端：即一個新的參與者在收獲之前所必須付出的能量。一個項目的切入能耗控制得越低越好。你的首要任務就是將切入能耗降低到能夠鼓勵人參與項目工作的水平。 以下各小節分別描述了開始一個新項目的一個重要的方面。排列順序大致是按照一個新的訪問者將遇到的情形安排的，當然你在實際操作時可以不按照這個順序進行。你可以將它們看作是一個檢查列表。當你開始一個項目時，只要一一檢查，確保每一步驟都做到了，或者在你省略某一部分時，至少你對將來可能出現的后果有把握就行了。 ### 選擇一個好名字 設想你是另外一個人，恰好聽說過你的項目，或者是是在搜索一個軟件來解決某個問題時碰巧看到了你的項目。他首先看到的是項目的名字。 一個好名字不會自然而然地使你的項目成功，而一個不好的名字也不會終結你的項目—當然了，一個*真正*糟糕的名字也許會，但是讓我們首先假定誰也不會迫不及待地讓自己的項目失敗吧。確實，一個不好的名字會延緩他人接受該項目的速度，要么是因為人們不會認真對待它，要么是因為人們很難記住它的名字。 一個好名字： - 告訴人們有關項目性質，或至少名字與性質是明顯相關聯的一些概念，這樣人們看到名字時就知道了項目能做什么，那么人們以后便很容易想起這個名字。 - 便于記憶。在此，我們必須承認英語實際上已成為網絡默認語言這一事實。“便于記憶”就意味著“便于能閱讀英語的人記憶”。例如，某一非英語發音的雙關語對于該語言之外的許多能閱讀英語的人來說是很難理解的。要是這個雙關語特別精彩并且令人難忘，那或許值得一試；但必須記住，這個名字在許多人的腦海里并不會產生在母語人士身上所有的效果。 - 不與另一個項目重名，也不侵犯任何商標權。這既表現職業美德，也是良好的法律意識。你要避免制造身份混亂。即便沒有不同的東西重名的現象，我們現在要搞清楚網絡上已有的東西已經很不容易了。 在前面[the section called “但首先環顧四周”](# "但首先環顧四周")里提及的資料有助于你發現是否另一個項目已經采用了你正在考慮的名字。免費的商標搜索見[http://www.nameprotect.org/](http://www.nameprotect.org/)和[http://www.uspto.gov/](http://www.uspto.gov/)。 - 盡可能成為`.com`、`.net`、以及`.org`頂級域中的一個域名。你應該選擇其中的一個，或許是`.org`吧，作為項目正式的網址；而另外兩個網址都轉發到前一個，這還可以防止其他人用項目的名字制造身份混亂。即使你打算將項目放在其它的網站空間上，（見[the section called “包裝主機”](# "包裝主機")），你仍然可以注冊自己項目的域名，而轉發至你存放項目的主頁上。對用戶來說，使用一個容易記憶的URL是十分有幫助的。 ### 有一份清楚的使命陳述 人們找到了項目的網頁之后，下一步就要看一份簡短的項目描述，即使命陳述，以便（在30秒之內）決定他們是否對該項目有興趣并獲取更多信息。因此，這份使命陳述必須放在首頁顯著的位置，最好是緊貼著項目名字的下方。 使命陳述必須具體，緊湊；而最重要的是簡短。以下是一個很好的例子，來自[http://www.openoffice.org/](http://www.openoffice.org/)： > *創建一個以社區為基礎，領先的國際化辦公室套件，能夠在所有主要的平臺上運行，并借基于API和XML文件格式的開放組件，提供對所有功能和數據的接入性。* 這份使命陳述僅僅用了簡短的幾句話，通過大量依賴讀者已有的知識明白無誤地傳達了所要傳達的信息。 “以社區為基礎”表明該軟件不受任何一家大公司控制其開發；“*國際化*”指的是該軟件允許人們在本地及多種語言環境下工作；“*所有主要的平臺*”說的是該軟件可移植到Unix，蘋果和視窗操作系統。其余的文字則說明開放接口以及易讀的文件格式都是該軟件目標中重要的組成部分。這份使命陳述并沒有在字面上告訴讀者它旨在成為微軟Office的開源替代品，但是人們從字里行間便能看出它的含義。乍一看，這份使命陳述似乎有些空泛，但實際上界定得相當明確：“*辦公室套件*”對那些熟悉這個軟件的人來說是非常具體的東西。在此，讀者已有的知識（這里指的是讀者有可能對微軟Office軟件的了解）又一次用來把使命陳述變得簡潔明了了。 一份使命陳述的性質不單單是由它所描述的軟件決定的，而在一定程度上得看是由誰來寫的。例如，OpenOffice.org使用"*以社區為基礎*"這個詞是很有道理的，因為這個項目最初是由Sun Microsystems發起，而至今仍主要是由這家公司贊助的。在其使命陳述中使用"以社區為基礎"這幾個字，Sun表明它對一些擔心該公司有可能試圖壟斷開發這一軟件的憂慮是有敏感度的。這樣的處理方法，即表明對一個有可能出現的潛在的問題有意識，就給將來完全避免這個問題的出現奠定了很好的基礎。話又說回來，如果項目并非由一家大公司贊助，那或許根本不需要這樣的詞語；說到底，社區開發已經成為今天的模式了，因而沒有理由要特別將那樣的詞語寫在使命陳述中。 ### 聲明項目是自由軟件 看過使命陳述之后仍對項目有興趣的人自然想要了解更多的情況，或許要看一看用戶文件和開發人員文件，最終可能下載一些東西。但在做這些事情以前，他們要確定這是一個開源項目。 *網站的首頁必須清清楚楚地寫明這是一個開源項目。*這看起來好像無需加以強調，但是你會驚訝有多少項目忽略了這一點。我見過不少自由軟件網站，其首頁不但沒有說明該軟件是在哪一個自由許可證下發布的，而且根本沒在首頁表明這是一個自由軟件。有時候這一至關重要的信息被次要地放在了下載頁，或是開發人員頁，或是其它的一個需要多點擊一次鼠標才能看到的一個地方。在一些極端的例子中，網頁上哪兒都找不到自由許可證—只有下載軟件打開之后才能看到。 別犯這個錯誤。這一忽略有可能讓你失去許多潛在的開發人員和用戶。務必在首頁，也就是使命陳述的正下方，聲明該項目是“自由軟件”或是“開源軟件”，并注明確切的許可證。有關選擇許可證的快速指南，見本章后面的[the section called “選擇許可證并應用”](# "選擇許可證并應用")，而有關許可證問題的詳細討論見[Chapter?9, *許可證，版權和專利*](# "Chapter?9.?許可證，版權和專利")。 至此，我們假想中的訪問者已經決定—或許在隨后的一分鐘之內—他打算至少再花5分鐘的時間研究一下這個項目。下面幾個小節要描述他在之后的5分鐘里將遇到的情形。 ### 特性和需求列表 你應該列出一個簡短的清單，說明軟件支持的各種特性（如果某些特性還未完成，也可以列出，但是在旁邊注明*計劃中*”或“*建設中*”），以及運行該軟件所要求的系統環境。列這份清單時，你只要設想一個人請你簡短地介紹這個軟件的特性/需求是什么。通常，那只是按照邏輯對使命陳述作進一步的擴充。例如，使命陳述可能寫的是： > *創建一個全文索引器并配備豐富API的搜索引擎，用于編程人員搜索大批量文本文件。* 特性和需求清單將列出更詳細的內容，對使命陳述的范圍加以說明： > *特性：* > > - > *搜索純文本，HTML和XML文件* > - > *字或詞搜索* > - > *（計劃中）模糊匹配* > - > *（計劃中）增量更新索引* > - > *（計劃中）索引遠程站點* > *需求：* > > - > *Python 2.2或更高版本* > - > *足夠的硬盤空間以儲存索引（大約原文件大小的2倍）* 有了這樣的信息，讀者便能很快地決定這個軟件是否適用于他們，也可以考慮是否以開發人員的身份參與其中。 ### 開發狀態 人們總是希望了解一個項目的狀況。對新的項目，他們想知道項目的承諾和現實之間存在著多大的距離。對成熟的項目，他們想知道維護得如何，新發布的頻率怎樣，以及對Bug報告反應的及時性等等。 要回答這些問題，你應該建立開發狀態頁，列出項目的近期目標和需求（例如，需要具備某方面專長的開發人員）。開發狀態頁也可以列出過去發布的記錄，其中包含特性清單，以便訪問者了解項目是如何定義“進展”的，并根據這一定義了解項目進展的速度。 別因為你的項目看起來沒準備好而感到害怕，也不要向夸大開發狀態的誘惑妥協。誰都清楚軟件是分階段開發的產品；你不必覺得難以開口說出：“這是仍帶有Bug的alpha軟件，它可以運行。而且至少有時候能正常工作，但你使用這個軟件就得自己承擔風險。”這類語言不會嚇跑你在這個階段需要的開發人員。然而，對于用戶來說，最糟糕的事情莫過于在軟件準備好之前就吸引用戶。一旦冠上了穩定性差或是Bug多多的名聲，軟件就很難再正名了。采取保守的策略對長遠的目標是非常有益的；軟件的穩定性超出用戶的預期總比達不到用戶的期望*好得多*，而給用戶驚喜就會給產品帶來最佳口碑。 **Alpha和Beta** 術語*alpha*這個詞通常指的是第一次發布，但是用戶可以使用該軟件進行工作，并且軟件也具備了最初計劃的所有功能，但已知的Bug仍然存在。Alpha軟件的主要目的在于獲取回饋，以便開發人員了解他們應該做什么。下一個階段，*beta*是指軟件中所有厲害的Bug都已經被消滅了，但是軟件還未經過足夠的測試，因而還不能正式發布。Beta軟件的目的有二，一是在未發現Bug的情況下正式發布軟件，二是提供給開發人員詳細的回饋，以便他們能夠盡快解決問題之后正式發布軟件。Alpha和Beta的差別通常是由判斷而決定的。 ### 下載 應該可以以標準格式下載軟件的源代碼。在一個項目剛起步時，二進制（可執行的）軟件包不是必要的，除非該軟件的構建和依賴要求相當復雜，以至于僅僅運行該軟件就需要大量的人力投入。 （如果情況是那樣的話，該項目也將很難吸引開發人員的參與！） 發行機制應該盡量做到方便，標準化以及清楚無誤。假如你要根除一種疾病，你分發的藥物不會是需要一種非標準化的注射器來操作的吧。同樣的道理，軟件應該與標準化的構造和安裝方法相一致；一個軟件距離標準化越遠，用戶和開發人員放棄該軟件并且一頭霧水地離開的可能性就越大。 那聽起來是顯而易見的道理，但是許多項目往往等到很晚的時候才動手解決標準化安裝程序，因為他們總是告訴自己這一步什么時候都可以做：*“等到代碼接近完工的時候再來解決這些所有的問題吧。”*殊不知在拖延完成軟件建設和安裝程序這類枯燥工作的時候，他們實際上是在推遲完成代碼的時間—因為他們讓一些本來可以為軟件編程做貢獻的開發人員失去了興趣。最糟糕的是，他們根本就*不知道*他們失去了那些開發人員，因為那是一連串無果而終的一個過程：某人拜訪了一個網頁，下載了軟件，試圖參與構建，失敗了，放棄而離開了。除了拜訪者本人以外，誰會知道發生了這一切？項目參與者中誰也不會意識到某位拜訪者的興趣和良好意愿在悄無聲息中便被扼殺了。 枯燥但具有高回報的工作應該盡早完成，而通過良好包裝便能夠大大降低進入項目障礙的工作顯然是具有很高的回報率的。 當你發布一個可以下載的軟件包時，至關重要的一點是給予這一次發布一個獨一無二的版本號碼，以便人們對兩次發布加以比較，從而了解哪些東西被替代了。有關版本編號的詳細討論見[the section called “版本號”](# "版本號")，而構建和安裝程序標準化的詳細內容見[the section called “打包”](# "打包")以及[Chapter?7, *打包、發布和日常開發*](# "Chapter?7.?打包、發布和日常開發")。 ### 版本控制和Bug跟蹤訪問 下載源碼軟件包對于只想安裝和使用軟件的人來說足矣，但對于想要解決bug問題或增加新特性的那些人就不夠了。盡管每夜源代碼快照會有些幫助，但是對一個活躍的開發社區來說，仍然不夠細致。人們需要實時進入最新的代碼系統，而能夠實現這一點的途徑便是使用版本控制系統。如果一個人在匿名情況下便可以獲取受版本控制的代碼，那就意味著該軟件對用戶和開發人員昭示：項目正努力為人們的參與創造條件。要是你不能馬上提供版本控制，也應該出一個聲明，告知人們你會盡快那樣做。有關版本控制的基礎架構詳見[Chapter?3, *技術基礎設施*](# "Chapter?3.?技術基礎設施")中的[the section called “版本控制”](# "版本控制")。 對于項目的Bug跟蹤系統來說，也是同樣的道理。Bug跟蹤系統之所以重要不只因為它對開發人員十分有用，而且對關注項目的人來說是一種標志。在許多人看來，一個可以進入的Bug數據庫是一個項目是否嚴肅認真的重要標志之一。再者，數據庫中的Bug數量越多，項目看起來越好。這聽起來似乎有悖常理，但是請記住Bug數量的記錄實際上取決于三個因素：軟件中存在的Bug絕對數量，使用該軟件的用戶人數，以及用戶記錄新發現的Bug的方便程度。在這三個因素當中，后兩個比前一個重要得多。任何具有一定規模和復雜性的軟件基本上都存在一定數量有待被發現的Bug。真正的問題是，一個項目在記錄和優先解決Bug問題方面做得有多好？如果一個項目有一個較大而又維護得很好的Bug數據庫（意思是bug問題得到及時地回應，重復bug被合并等等），那么這個項目就會比那些沒有Bug數據庫，或者Bug數據庫里空空如也的項目給予人們更好的印象。 當然，如果你的項目剛剛起步，那么Bug數據庫里就只有為數不多的Bug，而對此你也沒有什么辦法。但是如果在開發狀況頁強調項目仍處于初創期，且人們看到bug數據庫里大多數的文檔都是近期建立的，他們便可以由此推斷出該項目仍然有良好的解決*率*，也就不會因為看到相對較低的已經記錄的Bug絕對數量而產生不適當的警覺。 請注意Bug跟蹤系統的用途不止追蹤軟件的Bug，而且也用來跟蹤擴展請求，文檔變更，待解決的任務，以及其它一些問題。運行一個Bug跟蹤系統的詳細內容見[Chapter?3, *技術基礎設施*](# "Chapter?3.?技術基礎設施")中的[the section called “Bug跟蹤”](# "Bug跟蹤")，所以在此我就不贅述了。重要的是，Bug跟蹤*一定*要顯示出來，而且要確保項目的首頁上便能看到這一點。 ### 溝通渠道 項目的訪客通常都希望知道如何能聯系上參與項目的有關人員。提供郵件列表地址、聊天室、IRC頻道、以及任何其它形式的論壇，以便其他參與項目的人同樣可以聯系上。告訴人們你和項目的其他有關人員都在郵件列表上，因而人們便知道他們有途徑將回饋傳遞給開發人員。你在郵件列表上并不意味著你承諾回答所有的問題，也不等于你要滿足所有人提出的有關特性的要求。長遠來看，大多數用戶或許根本從不參與論壇，然而，如果他們知道他們需要的時候*可以*那樣做，那對他們就是一種欣慰。 在項目開發初期，沒有必要將用戶論壇與開發人員論壇分開。更好的辦法是讓所有與軟件有關的人員在“同一間屋子”里進行交談。在早期使用軟件的人當中，開發人員與用戶之間的界線通常很模糊；不是沒有界線，但是開發人員與用戶之間的比例在項目早期遠遠高于后面的階段。盡管我們不能假設每一位早期與項目有關的人都是想要介入軟件開發的編程人員，但是我們可以肯定他們至少很有興趣地關注項目發展中進行的討論，并了解項目發展的方向。 由于本章只討論項目的初建，所以在此我們只要說明有必要建立以上所說的交流論壇就行了。稍后，在[Chapter?6, *交流*](# "Chapter?6.?交流")中的[the section called “處理成長”](# "處理成長")，我們將討論在什么地方以及如何建立這樣的論壇，及可能需要的協調和其它方面的管理，另外，在時機成熟的時候，如何分離用戶與開發人員的論壇而避免造成無法逾越的鴻溝。 ### 開發者指南 如果有人考慮參與項目，她會尋找開發者指南。與社會性文檔相比，開發者指南通常沒有很多的技巧：只需要解釋開發者之間，以及與用戶之間如何交互，以及如何最終完成任務。 這部分的細節可以看[Chapter?4, *社會和政治的基礎架構*](# "Chapter?4.?社會和政治的基礎架構")中的[the section called “寫下所有的內容”](# "寫下所有的內容")，但開發指南的基本元素包括： - 與其它開發者交流論壇的鏈接 - 報告Bug和提交補丁的指導 - 說明進行開發的*方法*—項目是仁慈專制、還是民主的、還是其它。 對于“專制”這里沒有任何輕蔑的含義。如果存在一個開發者對所有變更擁有否決權，這完全沒有問題。許多成功的項目以這種方式進行。關鍵是項目能夠說出來它的做法。一個假裝民主的獨裁會讓人厭惡；如果獨裁者只要有能力并被信任，一切都會很好。 完整的開發者指南實例可以看[http://svn.collab.net/repos/svn/trunk/www/hacking.html](http://svn.collab.net/repos/svn/trunk/www/hacking.html)，或者是更加關注管理和參與精神，而較少關注技術事務的[http://www.openoffice.org/dev_docs/guidelines.html](http://www.openoffice.org/dev_docs/guidelines.html)。 為程序員提供單獨的軟件指導的問題會在本章后面的[the section called “開發者文檔”](# "開發者文檔")討論。 ### 文檔 文檔非常必要。需要有一些用戶可以讀的*內容*，即使它非常基本和不完整。在初期這樣做確實是一件“苦差事”，經常成為新開源項目的第一個失敗之處。提出使命聲明和特性列表、選擇一個許可證、概述開發狀態—這都是相對的小任務，完成后通常可以不必返回繼續工作。而另一方面，文檔永遠沒有真正的結束，這可能也是人們總是延遲開始文檔的一個原因。 一個隱伏的事實是，文檔對于編寫者的功用與閱讀者的功用是相反的。對于初始用戶來說最重要的是基礎文檔：如何快速配置軟件，軟件如何工作的概述以及一些常規操作的指導。而這些通常是*編寫者*所非常熟悉的內容—以至于很難從讀者的角度看問題，因而他們不會費力去表述一些非常明顯而不值一提的步驟。 對這個問題沒有神奇的解決辦法。必須有人坐下來寫好內容，然后交給普通的用戶來驗證它的質量。使用簡單和容易編輯的格式，例如HTML、純文本、Texinfo或一些XML的變種—便于在激勵下可以輕型和快速的作出改進。這不僅是為了消除最初作者進行增量改進所帶來的代價，也是為了希望修改文檔的新加入者。 一個保證基本初始文檔完成的方法是預先限制其范圍。這種方法至少不會讓我們感覺是在完成一個開放結尾的任務。一個經驗是它必須達到下面的最低標準： - 告訴讀者他們所需的技術技能。 - 清楚和完整的描述如何配置軟件，并在文檔的開頭部分告訴用戶如何運行確認安裝成功的診斷測試或簡單命令。啟動文檔有時候比使用文檔更重要。一個人投入到軟件安裝和開始的努力越多，她就越有可能持續的搞明白沒有很好文檔描述的高級功能。當人們放棄時，他們會很早就放棄；因此，在早期階段，例如安裝時，需要最多的支持。 - 提供一個普通任務的教程式的實例。很顯然，不同任務的例子越多越好，但是時間有限，最好還是選擇一個任務并完整的完成它。一旦人們看到這個軟件*可以*使用，他們會開始探索其他需要的功能—如果你足夠幸運，他們會自己補充文檔。這將會讓我們到下一點... - 標示文檔中未完成的部分。通過向讀者展示這些不足，可以實現你與他們觀點的聯盟。你的移情作用可以使他們恢復信心，不必為確定什么是項目最重要的事情而掙扎。這些標示不需要承諾填補這些空白的期限—它等于是合情合理的公開征集志愿者。 最后一點更廣泛重要，也更實際，并可以應用到整個項目中，而不僅僅是文檔中。開源領域中一個都知道的問題就是項目規范。你不必夸大項目的這種短處，你只需小心冷靜的識別出需要這種規范（說明文檔、Bug跟蹤數據庫或郵件列表討論中都可以）的場景。就項目而言，沒有人會視其為失敗主義，也不會認為這是對在特定日期完成的承諾，除非項目明確作出這種承諾。因為使用軟件的所有人都會發現這種不足，他們最好能在心理上做好準備—然后項目就有了解決這些問題的堅實知識。 **維護FAQ** 一個*FAQ*（“常見問題列表”）就教育意義的回報來講，可能是最好的投資之一。非常提倡將FAQ調整為用戶和開發者實際提出的問題—而不應該是你*期望*他們提出的問題—因此，一個維護良好的FAQ可以讓咨詢者從中準確的找到尋找的答案。在遇到問題時，FAQ通常是用戶首先查找的地方，甚至比正式手冊更受人偏愛，可能成為其他站點鏈接最多的文檔。 但很不幸，你不可能在項目的開始就完成FAQ。好的FAQ不是寫成的，而是長成的。它們是通過定義響應文檔，隨著人們對軟件的日常使用而進化。因為不能預感到用戶將會提出的問題，所以我們無法從頭開始編寫有用的FAQ。 因此，不要在這方面浪費時間了。但無論如何，你或許會發現創建一個FAQ的空白模板會很有用，很明顯這樣可以幫助人們在項目進行中貢獻問題和答案。此時，最重要的性質不是完整，而是方便：如果添加FAQ非常簡單，人們就會去添加。 （正確的FAQ維護應該是特殊和迷惑性的問題，將會在[Chapter?8, *管理志愿者*](# "Chapter?8.?管理志愿者")的[the section called “FAQ管理員”](# "FAQ管理員")詳細討論。） ### 文檔的可用性 在兩個地方必須有文檔：在線（直接在網站上），*以及*軟件可下載分發版本（見[Chapter?7, *打包、發布和日常開發*](# "Chapter?7.?打包、發布和日常開發")的[the section called “打包”](# "打包")）中。它必須以可瀏覽的形式在線，因為通常人們會在第一次下載軟件*之前*首先閱讀文檔，以決定是否下載。但是也必須和軟件配套，因為原則上下載中必須包括使用軟件包的所有必須內容。 對于在線文檔，要確定有一個指向包含*完整*文檔的（請在鏈接旁注明"monolithic"或"all-in-one"或"single largepage"，以提醒人們知道需要更長的下載時間）單獨HTML頁的鏈接。這是因為人們經常會在整個文檔中尋找特定的詞匯或短語。通常是他們已經知道他們在找什么；只是記不住具體的章節。對于此類人，最郁悶的就是遇到一個目錄頁面、然后是指導頁面、然后是安裝指導等等。當頁面是如此瑣碎時，瀏覽器的搜索功能將變得毫無作用。分頁的樣式適合那些知道他們所需章節，或是從頭到尾閱讀的人。但這*不是*訪問文檔的常規方式。通常是某人已經熟悉了軟件，返回來搜索特定的詞匯或短語。如果未能提供一個單獨的、可搜索的文檔會讓他們活的很辛苦。 ### 開發者文檔 開發者文檔主要為了幫助程序員理解代碼，從而修改和擴展軟件。這與更關注社交性而不是技術性的*開發者指南*有些許不同。開發者指南告訴程序員如何與代碼本身打交道。為了方便，這兩個文檔通常會整理為一份文檔（例如前面提到的[http://svn.collab.net/repos/svn/trunk/www/hacking.html](http://svn.collab.net/repos/svn/trunk/www/hacking.html)），但是這不是必須的。 盡管開發者文檔可能很有用，但也沒有為了它而影響發布。只要原始作者還在而且愿意，就可以回答關于代碼的問題，一開始這就足夠了。實際上，反復回答相同的問題是編寫這個文檔的動力所在。但即使文檔還沒有寫，堅定地參與者也依然會設法以自己的方式處理代碼。驅使人們花時間研究代碼基的原因是他們發現這些代碼對他們有用。如果人們相信這一點，他們就會花時間去搞明白；如果他們不相信，再多的開發者文檔也留不住他們。 如果你有時間為一個讀者寫文檔，那還是寫給所有用戶吧。所有用戶的文檔，和開發者文檔有同樣的效果；為軟件工作的程序員一定對如何使用也非常熟悉。之后，當你看到程序員反復詢問相同的問題時，你就應該為他們編寫單獨的文檔。 一些項目使用wiki作為初始文檔，甚至作為他們主要的文檔。在我的經驗里，只有文檔是被少數認可文檔的組織方式和包含內容的成員編輯時，才能正常工作。更多細節在[Chapter?3, *技術基礎設施*](# "Chapter?3.?技術基礎設施")的[the section called “Wikis”](# "Wikis")。 ### 輸出和屏幕截圖實例 如果一個項目包含圖形化的用戶界面，或者生成圖形和其他特別的輸出，那么就應該將這些樣例放到項目網站上。如果是界面，那應該是截圖；對于輸出，可以是截圖或只是文件。但是為了迎合人們立刻滿足的需要：一個單獨的截圖比大段描述文字和郵件列表的嘮叨更讓人信服，因為截圖是軟件能正常*工作*的不容爭辯的證據。它可能充滿bug、可能難于安裝、可能文檔不全，但是截圖是一個人投入足夠的精力，可以使之運行的證據。 **屏幕截圖** 如果沒做過截圖，可能會感覺有點麻煩，這里是一些制作截圖的基本指導。使用Gimp（[http://www.gimp.org/](http://www.gimp.org/)），打開File->Acquire->Screenshot，然后選擇Single?Window或 Whole?Screen，然后點 OK。然后你的下一次鼠標點擊就會捕捉窗口或屏幕，成為Gimp的一個文件。如果必要，還可以對圖像進行剪裁和大小調整，相關指導在[http://www.gimp.org/tutorials/Lite_Quickies/#crop](http://www.gimp.org/tutorials/Lite_Quickies/#crop)。 還有一些東西需要放置到網站中，如果你有時間，或者如果出于某種原因而顯得特別合適：一個新聞頁、一個項目歷史頁、一個相關鏈接頁、站點搜索特性和捐贈頁等等。開始時這些都不是必要的，但將來要一直留意。 ### 包裝主機 有一些站點為開源項目提供免費的主機和基礎設施：web站點、版本控制、bug跟蹤、下載區、討論論壇和定期備份等等。具體細節站點之間各不相同，通過使用這些站點，你可以免費得到基礎服務。但是很明顯你也同時放棄了通過用戶經驗，來進行細化控制的能力。主機服務決定了站點運行的軟件，也控制了或至少影響了項目站點的感觀。 [Chapter?3, *技術基礎設施*](# "Chapter?3.?技術基礎設施")的[the section called “包裝主機”](# "包裝主機")是包裝主機優缺點的詳細討論，也有提供這種服務的站點列表。