2. 起步 | 制造开源软件 – 如何成功运营自由软件项目

# 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 “包装主机”](# "包装主机")是包装主机优缺点的详细讨论，也有提供这种服务的站点列表。