Índice
O modelo clássico de como os projectos de software livre são criados foi dado por Eric Raymond, num artigo bem conhecido sobre os processos open source entitulado The Cathedral and the Bazaar. Ele escreveu:
Qualquer boa peça de sofware começa quando o programador coça a sua própria comichão.
Repare que Raymond não está afirmando que os projectos open source acontecem apenas quando alguém tem "comichão". Antes, está afirmando que bom software resulta quando o programador tem um interesse pessoal na resolução do problema; a relevância desta realidade para o software livre é a de que "comichões" particulares foram a motivação mais frequente para iniciar um projecto de software livre.
É ainda desta forma que grande parte dos projectos de software livre tem início, mas não tanto como em 1997, quando Raymond escreveu aquelas palavras. Hoje temos o fenómeno das organizações—incluíndo empresas cons fins lucrativos—dando início a projectos open source grandes e geridos centralmente, criados de raíz. O programador solitário, criando algum código para resolver um problema local e notando depois que o resultado tem aplicabilidade mais geral, é ainda a fonte de muito do novo software livre, mas não é caso único.
A afirmação de Raymond, todavia, ainda é pertinente. A condição essencial é a de que os produtores do software tenham um interesse directo no seu sucesso, porque eles mesmos o utilizam. Se o software não faz o que é suposto fazer, a pessoa ou organização que o produz vai sentir esta insatisfação no seu trabalho diário. Por exemplo, o projecto OpenAdapter (http://www.openadapter.org/), iniciado pelo banco de investimento Dresdner Kleinwort Wasserstein como uma plataforma open source para integrar sistemas díspares de informação financeira, dificilmente pode ser considerado como "coçando a comichão" de algum programador individual. Porém, certamente atenua uma "comichão institucional". Essa comichão resulta directamente das experiências da instituição e dos seus parceiros e, por isso, se falhar nessa atenuação que traz, eles o saberão. Este mecanismo produz bom software porque o ciclo de realimentação dá-se na direcção correcta. O programa não está sendo escrito para ser vendido a terceiros para que possam resolver o seu problema. Está sendo escrito para resolver o próprio problema do autor, sendo depois partilhado com todos, tal como se de uma doença se tratasse e o software fosse o medicamento cuja distribuição se destinasse à total erradicação da epidemia.
Este capítulo é sobre como introduzir um novo projecto de software livre ao mundo, mas muitas das suas recomendações soariam familiares a uma organização de saúde distribuíndo medicamentos. Os objectivos são muito semelhantes: queremos mostrar claramente o que faz o medicamento, colocá-lo nas mãos apropriadas e garantir que os que o recebem sabem administrá-lo. Com software, porém, queremos também atrair alguns dos destinatários a fim de se juntarem ao esforço contínuo de investigação para melhorar o medicamento.
A distribuição de software livre tem duas faces. O software precisa de ganhar utilizadores e de ganhar programadores. Estas duas necessidades não estão necessariamente em conflito, mas acrescentam alguma complexidade à apresentação inicial de um projecto. Alguma informação é útil a ambas as audiências, enquanto outra é útil apenas a uma delas. Os dois tipos de informação devem subscrever o princípio da apresentação escalada; o grau de detalhe apresentado em cada passo deve corresponder directamente ao tempo e esforço dispendidos pelo leitor. Maior esforço deve sempre significar maior compensação. Quando os dois elementos não se correlacionam devidamente, poderá haver desmotivação e deixa de haver investimento de esforço.
O corolário disto é que as aparências importam. Os programadores, em particular, muitas vezes não gostam de acreditar nisto. O seu gosto pela substância em vez da forma é quase motivo de orgulho profissional. Não é por acaso que tantos programadores exibem uma antipatia pelo trabalho de marketing e relações públicas, ou que designers gráficos profissionais ficam frequentemente horrorizados com o que surge das mãos dos programadores.
É uma pena, pois há situações onde forma é substância e a apresentação de um projecto é uma delas. Por exemplo, a primeira coisa que um visitante aprende a respeito de um projecto é qual o aspecto do seu site web. Esta informação é absorvida antes de qualquer conteúdo ser apreendido—antes mesmo de se ler qualquer texto ou clicar em links. Por muito injusto que possa parecer, não se pode impedir ninguém de formar uma primeira impressão imediata. A aparência do site mostra se foi tomado cuidado ao organizar a apresentação do projecto. Os seres humanos têm antenas muito sensíveis para detectar a aplicação de cuidado. A maioria de nós pode dizer de relance se um site foi feito apressadamente ou se foi pensado com cuidado. Esta é a primeira informação que o seu projecto envia; a impressão que cria vai afectar o restante do projecto por associação.
Logo, embora grande parte deste capítulo fale sobre o conteúdo com que o seu projecto deve iniciar, lembre-se que a sua aparência também é importante. Visto que o site web do projecto deve atender a dois tipos distintos de visitantes—utilizadores e programadores— especial atenção deve ser dada à clareza. Embora este não seja o lugar para um tratado geral sobre design web, um princípio é suficientemente importante para ser mencionado, sobretudo quando o site serve múltiplas (eventualmente sobrepostas) audiências: as pessoas devem ter uma ideia aproximada do destino de um link antes de clicá-lo. Por exemplo, deveria ser óbvio ao olhar para os links para a documentação dos utilizadores que aqueles levam à documentação dos utilizadores e não, por exemplo, à documentação para programadores. Gerir um projecto serve em parte para fornecer informação, mas também para dar conforto. A mera presença de certos atributos habituais, em locais esperados, dá segurança a utilizadores e programadores que estão decidindo se se querem envolver. Dá sinal de que o projecto está estruturado, antecipou as questões que serão feitas e que fez um esforço para responder a elas de um modo suave para quem pergunta. Transmitindo esta aura de preparação, o projecto envia a mensagem: "O seu tempo não será desperdiçado se você se envolver," que é exactamente o que as pessoas precisam de ouvir.
Antes de iniciar um projecto open source, há um aspecto importante:
Verifique sempre se já existe algum projecto que faça o que quer. Há uma boa possibilidade de que, para o problema que quer resolver, já alguém o tenha resolvido anteriormente. Se de facto o resolveu, lançando o código sob uma licença livre, não há motivo para reinventar a roda hoje. Há excepções, naturalmente: se quer iniciar um projecto como uma experiência educacional, código pré-existente não ajuda; ou talvez o projecto que tem em mente seja tão especializado que você sabe que é nula a probabilidade de alguém o ter executado. Em geral, todavia, não há motivo para não procurar e os frutos podem ser consideráveis. Se os motores de busca habituais da Internet não apontam nada, tente pesquisar em http://freshmeat.net/ (um site de notícias de projectos open source, sobre o qual se falará mais tarde), em http://www.sourceforge.net/ e no directório de software livre da Free Software Foundation em http://directory.fsf.org/.
Mesmo se não encontrar exactamente o que procura, pode encontrar algo tão próximo que faz mais sentido aderir a esse projecto e acrescentar funcionalidade do que iniciar do nada.
Você procurou em volta, considerou que nada existente serve verdadeiramente as suas necessidades e decidiu iniciar um novo projecto.
E agora?
A parte mais difícil ao lançar um projecto de software livre é transformar uma visão própria numa colectiva. Você ou a sua organização podem saber perfeitamente o que pretende, mas expressar esse objectivo claramente ao mundo requer trabalho considerável. É, todavia, essencial que arranje tempo para o fazer. Você e os outros fundadores precisam de decidir em que consiste o projecto—isto é, decidir as suas limitações, o que não fará tal como o que fará— e enunciar uma declaração de missão. Esta parte não é em regra difícil, embora possa por vezes revelar pressupostos não declarados e até desentendimentos sobre a natureza do projecto, o que não é mau de todo: é preferível resolvê-los agora do que depois. O passo seguinte é preparar o projecto para consumo público, consistindo basicamente em meras rotinas.
O que o torna tão trabalhoso é o facto de consistir sobretudo em
organizar e documentar coisas que todos sabem—"todos", isto é, os
que estão envolvidos no projecto até então. Não há por isso, para os que
trabalham no projecto, um benefício imediato. Não precisam de um ficheiro
README dando uma visão global do projecto, nem de
um documento de design ou um manual de utilizador. Não precisam de uma
árvore de código cuidadosamente preparada e conforme aos padrãos informais
mas difundidos das distribuições de software livre. Qualquer que seja o
modo de arranjo do código, está bem para eles, porque estão habituados a
ele e, se o código é executável, sabem como usá-lo. Não lhes interessa
se os pressupostos arquitecturais fundamentais do projecto não estão
documentados; estão familiarizados com eles também.
Os novos utilizadores, por outro lado, precisam destas coisas. Felizmente, não precisam delas de uma vez só. Não é necessário fornecer todos os recursos possíveis antes de dar a conhecer o projecto. Num mundo perfeito, talvez, qualquer novo projecto open source começaria com um documento de design exaustivo, um manual de utilizador completo (com marcas especiais para funcionalidades planeadas mas ainda não implementadas), código preparado de forma portável e estética, capaz de correr em qualquer plataforma de computação, e por aí fora. Na realidade, tomar conta de todas estas «pontas» significaria um consumo de tempo impraticável e, de qualquer modo, é trabalho no qual se espera que voluntários venham a colaborar quando o projecto estiver em curso.
O que é necessário, todavia, é que seja feito um investimento suficiente na apresentação de forma a que novos visitantes possam ultrapassar o obstáculo inicial do desconhecimento. Pense nisso como o primeiro passo de um processo de arranque, para levar o projecto a um tipo de energia de activação mínima. Tenho ouvido designar este ponto de energia de hactivação[13]: o esforço mínimo que um visitante deve empregar até obter retorno. Quanto menor for esta energia, melhor. A sua primeira tarefa é diminuir a energia de hactivação o suficiente para encorajar o envolvimento de outras pessoas.
Cada uma das seguintes subsecções descreve um aspecto importante do arranque de um novo projecto. São apresentadas numa ordem que aproxima aquela com que são deparados os visitantes, embora naturalmente a sua implementação possa surgir numa ordem distinta. Pode considerá-la como uma checklist. Ao iniciar um projecto, percorra esta lista e garanta que cada item está coberto (ou que tem noção das consequências de ignorar algum deles).
Coloque-se no lugar de alguém que tomou recentemente conhecimento do seu projecto, talvez encontrando-o enquanto procurava resolver algum problema. A primeira coisa que encontrará é o nome do projecto.
Um bom nome não trará sucesso automaticamente ao seu projecto, e um mau nome não será fatal—bom, talvez um nome realmente mau pudesse ser, mas assumimos que ninguém quer fazer fracassar intencionalmente o seu projecto. Todavia, um mau nome pode diminuir a adopção do projecto, pelo facto de não ser levado a sério ou simplesmente porque as pessoas têm dificuldade em lembrá-lo.
Um bom nome:
Dá ideia do que o projecto faz ou, pelo menos, o que tem com ele uma relação óbvia, de forma que o nome surge naturalmente, conhecendo-se o propósito do projecto.
É fácil de lembrar. Não podemos fugir aqui ao facto de o Inglês ser a língua estabelecida da Internet: "fácil de lembrar" significa "fácil de lembrar para alguém que lê Inglês convenientemente." Nomes que são trocadilhos dependentes da pronúncia natural inglesa, por exemplo, serão opacos para muitos leitores sem Inglês como língua materna. O trocadilho pode justificar o risco; mas pense que muitos não verão o nome da mesma forma que um falante natural de Inglês.
Não é o mesmo nome de qualquer outro projecto, e não infringe quaisquer marcas registadas. Trata-se apenas de bom senso e cortesia. Você não quer criar confusão de identidades. Já é suficientemente difícil registar tudo o que está disponível na Net, sem que coisas diferentes possuam o mesmo nome.
Os recursos mencionados acima em “Mas Primeiro, Procure em Redor” são úteis para descobrir se algum outro projecto já possui o nome que está a considerar usar. Pesquisas gratuitas de marcas estão disponíveis em http://www.nameprotect.org/ e http://www.uspto.gov/.
Se possível, está disponível como nome de domínio nos
domínios de topo .com,
.net e .org.
Deve escolher um, provavelmente .org,
para anunciar como página oficial do projecto;
os outros dois nomes devem reencaminhar para lá e servem apenas
para impedir que terceiros possam criar confusão em torno do
nome. Mesmo se pretender alojar o projecto noutro sítio (veja
“Canned Hosting”), pode sempre
registar domínios específicos e reencaminhá-los para o alojamento.
Isto ajuda os utilizadores a lembrar um único URL.
Once they've found the project's web site, the next thing people will look for is a quick description, a mission statement, so they can decide (within 30 seconds) whether or not they're interested in learning more. This should be prominently placed on the front page, preferably right under the project's name.
The mission statement should be concrete, limiting, and above all, short. Here's an example of a good one, from http://www.openoffice.org/:
To create, as a community, the leading international office suite that will run on all major platforms and provide access to all functionality and data through open-component based APIs and an XML-based file format.
In just a few words, they've hit all the high points, largely by drawing on the reader's prior knowledge. By saying "as a community", they signal that no one corporation will dominate development; "international" means that the software will allow people to work in multiple languages and locales; "all major platforms" means it will be portable to Unix, Macintosh, and Windows. The rest signals that open interfaces and easily understandable file formats are an important part of the goal. They don't come right out and say that they're trying to be a free alternative to Microsoft Office, but most people can probably read between the lines. Although this mission statement looks broad at first glance, in fact it is quite circumscribed: the words "office suite" mean something very concrete to those familiar with such software. Again, the reader's presumed prior knowledge (in this case probably from MS Office) is used to keep the mission statement concise.
The nature of a mission statement depends partly on who is writing it, not just on the software it describes. For example, it makes sense for OpenOffice.org to use the words "as a community", because the project was started, and is still largely sponsored, by Sun Microsystems. By including those words, Sun indicates its sensitivity to worries that it might try to dominate the development process. With this sort of thing, merely demonstrating awareness of the potential for a problem goes a long way toward avoiding the problem entirely. On the other hand, projects that aren't sponsored by a single corporation probably don't need such language; after all, development by community is the norm, so there would ordinarily be no reason to list it as part of the mission.
Those who remain interested after reading the mission statement will next want to see more details, perhaps some user or developer documentation, and eventually will want to download something. But before any of that, they'll need to be sure it's open source.
The front page must make it unambiguously clear that the project is open source. This may seem obvious, but you would be surprised how many projects forget to do it. I have seen free software project web sites where the front page not only did not say which particular free license the software was distributed under, but did not even state outright that the software was free at all. Sometimes the crucial bit of information was relegated to the Downloads page, or the Developers page, or some other place that required one more mouse click to get to. In extreme cases, the license was not given anywhere on the web site at all—the only way to find it was to download the software and look inside.
Don't make this mistake. Such an omission can lose many potential developers and users. State up front, right below the mission statement, that the project is "free software" or "open source software", and give the exact license. A quick guide to choosing a license is given in “Choosing a License and Applying It” later in this chapter, and licensing issues are discussed in detail in Capítulo 9, Licenses, Copyrights, and Patents.
At this point, our hypothetical visitor has determined—probably in a minute or less—that she's interested in spending, say, at least five more minutes investigating this project. The next sections describe what she should encounter in that five minutes.
There should be a brief list of the features the software supports (if something isn't completed yet, you can still list it, but put "planned" or "in progress" next to it), and the kind of computing environment required to run the software. Think of the features/requirements list as what you would give to someone asking for a quick summary of the software. It is often just a logical expansion of the mission statement. For example, the mission statement might say:
To create a full-text indexer and search engine with a rich API, for use by programmers in providing search services for large collections of text files.
The features and requirements list would give the details, clarifying the mission statement's scope:
Features:
Searches plain text, HTML, and XML
Word or phrase searching
(planned) Fuzzy matching
(planned) Incremental updating of indexes
(planned) Indexing of remote web sites
Requirements:
Python 2.2 or higher
Enough disk space to hold the indexes (approximately 2x original data size)
With this information, readers can quickly get a feel for whether this software has any hope of working for them, and they can consider getting involved as developers too.
People always want to know how a project is doing. For new projects, they want to know the gap between the project's promise and current reality. For mature projects, they want to know how actively it is maintained, how often it puts out new releases, how responsive it is likely to be to bug reports, etc.
To answer these questions, you should provide a development status page, listing the project's near-term goals and needs (for example, it might be looking for developers with a particular kind of expertise). The page can also give a history of past releases, with feature lists, so visitors can get an idea of how the project defines "progress" and how quickly it makes progress according to that definition.
Don't be afraid of looking unready, and don't give in to the temptation to hype the development status. Everyone knows that software evolves by stages; there's no shame in saying "This is alpha software with known bugs. It runs, and works at least some of the time, but use at your own risk." Such language won't scare away the kinds of developers you need at that stage. As for users, one of the worst things a project can do is attract users before the software is ready for them. A reputation for instability or bugginess is very hard to shake, once acquired. Conservativism pays off in the long run; it's always better for the software to be more stable than the user expected than less, and pleasant surprises produce the best kind of word-of-mouth.
The software should be downloadable as source code in standard formats. When a project is first getting started, binary (executable) packages are not necessary, unless the software has such complicated build requirements or dependencies that merely getting it to run would be a lot of work for most people. (But if this is the case, the project is going to have a hard time attracting developers anyway!)
The distribution mechanism should be as convenient, standard, and low-overhead as possible. If you were trying to eradicate a disease, you wouldn't distribute the medicine in such a way that it requires a non-standard syringe size to administer. Likewise, software should conform to standard build and installation methods; the more it deviates from the standards, the more potential users and developers will give up and go away confused.
That sounds obvious, but many projects don't bother to standardize their installation procedures until very late in the game, telling themselves they can do it any time: "We'll sort all that stuff out when the code is closer to being ready." What they don't realize is that by putting off the boring work of finishing the build and installation procedures, they are actually making the code take longer to get ready—because they discourage developers who might otherwise have contributed to the code. Most insidiously, they don't know they're losing all those developers, because the process is an accumulation of non-events: someone visits a web site, downloads the software, tries to build it, fails, gives up and goes away. Who will ever know it happened, except the person themselves? No one working on the project will realize that someone's interest and good will have been silently squandered.
Boring work with a high payoff should always be done early, and significantly lowering the project's barrier to entry through good packaging brings a very high payoff.
When you release a downloadable package, it is vital that you give a unique version number to the release, so that people can compare any two releases and know which supersedes the other. A detailed discussion of version numbering can be found in “Release Numbering”, and the details of standardizing build and installation procedures are covered in “Packaging”, both in Capítulo 7, Packaging, Releasing, and Daily Development.
Downloading source packages is fine for those who just want to install and use the software, but it's not enough for those who want to debug or add new features. Nightly source snapshots can help, but they're still not fine-grained enough for a thriving development community. People need real-time access to the latest sources, and the way to give them that is to use a version control system. The presence of anonymously accessible version controlled sources is a sign—to both users and developers—that this project is making an effort to give people what they need to participate. If you can't offer version control right away, then put up a sign saying you intend to set it up soon. Version control infrastructure is discussed in detail in “Version Control” in Capítulo 3, Technical Infrastructure.
The same goes for the project's bug tracker. The importance of a bug tracking system lies not only in its usefulness to developers, but in what it signifies for project observers. For many people, an accessible bug database is one of the strongest signs that a project should be taken seriously. Furthermore, the higher the number of bugs in the database, the better the project looks. This might seem counterintuitive, but remember that the number of bugs recorded really depends on three things: the absolute number of bugs present in the software, the number of users using the software, and the convenience with which those users can register new bugs. Of these three factors, the latter two are more significant than the first. Any software of sufficient size and complexity has an essentially arbitrary number of bugs waiting to be discovered. The real question is, how well will the project do at recording and prioritizing those bugs? A project with a large and well-maintained bug database (meaning bugs are responded to promptly, duplicate bugs are unified, etc.) therefore makes a better impression than a project with no bug database, or a nearly empty database.
Of course, if your project is just getting started, then the bug database will contain very few bugs, and there's not much you can do about that. But if the status page emphasizes the project's youth, and if people looking at the bug database can see that most filings have taken place recently, they can extrapolate from that that the project still has a healthy rate of filings, and they will not be unduly alarmed by the low absolute number of bugs recorded.
Note that bug trackers are often used to track not only software bugs, but enhancement requests, documentation changes, pending tasks, and more. The details of running a bug tracker are covered in “Bug Tracker” in Capítulo 3, Technical Infrastructure, so I won't go into them here. The important thing from a presentation point of view is just to have a bug tracker, and to make sure that fact is visible from the front page of the project.
Visitors usually want to know how to reach the human beings involved with the project. Provide the addresses of mailing lists, chat rooms, and IRC channels, and any other forums where others involved with the software can be reached. Make it clear that you and the other authors of the project are subscribed to these mailing lists, so people see there's a way to give feedback that will reach the developers. Your presence on the lists does not imply a committment to answer all questions or implement all feature requests. In the long run, most users will probably never join the forums anyway, but they will be comforted to know that they could if they ever needed to.
In the early stages of a project, there's no need to have separate user and developer forums. It's much better to have everyone involved with the software talking together, in one "room." Among early adopters, the distinction between developer and user is often fuzzy; to the extent that the distinction can be made, the ratio of developers to users is usually much higher in the early days of the project than later on. While you can't assume that every early adopter is a programmer who wants to hack on the software, you can assume that they are at least interested in following development discussions and in getting a sense of the project's direction.
As this chapter is only about getting a project started, it's enough merely to say that these communications forums need to exist. Later, in “Handling Growth” in Capítulo 6, Communications, we'll examine where and how to set up such forums, the ways in which they might need moderation or other management, and how to separate user forums from developer forums, when the time comes, without creating an unbridgeable gulf.
If someone is considering contributing to the project, she'll look for developer guidelines. Developer guidelines are not so much technical as social: they explain how the developers interact with each other and with the users, and ultimately how things get done.
This topic is covered in detail in “Colocar Tudo por Escrito” in Capítulo 4, Infra-estrutura Social e Política, but the basic elements of developer guidelines are:
pointers to forums for interaction with other developers
instructions on how to report bugs and submit patches
some indication of how development is usually done—is the project a benevolent dictatorship, a democracy, or something else
No pejorative sense is intended by "dictatorship", by the way. It's perfectly okay to run a tyranny where one particular developer has veto power over all changes. Many successful projects work this way. The important thing is that the project come right out and say so. A tyranny pretending to be a democracy will turn people off; a tyranny that says it's a tyranny will do fine as long as the tyrant is competent and trusted.
See http://subversion.apache.org/docs/community-guide/ for an example of particularly thorough developer guidelines, or http://www.openoffice.org/dev_docs/guidelines.html for broader guidelines that focus more on governance and the spirit of participation and less on technical matters.
The separate issue of providing a programmer's introduction to the software is discussed in “Developer documentation” later in this chapter.
Documentation is essential. There needs to be something for people to read, even if it's rudimentary and incomplete. This falls squarely into the "drudgery" category referred to earlier, and is often the first area where a new open source projects falls down. Coming up with a mission statement and feature list, choosing a license, summarizing development status—these are all relatively small tasks, which can be definitively completed and usually need not be returned to once done. Documentation, on the other hand, is never really finished, which may be one reason people sometimes delay starting it at all.
The most insidious thing is that documentation's utility to those writing it is the reverse of its utility to those who will read it. The most important documentation for initial users is the basics: how to quickly set up the software, an overview of how it works, perhaps some guides to doing common tasks. Yet these are exactly the things the writers of the documentation know all too well—so well that it can be difficult for them to see things from the reader's point of view, and to laboriously spell out the steps that (to the writers) seem so obvious as to be unworthy of mention.
There's no magic solution to this problem. Someone just needs to sit down and write the stuff, and then run it by typical new users to test its quality. Use a simple, easy-to-edit format such as HTML, plain text, Texinfo, or some variant of XML—something that's convenient for lightweight, quick improvements on the spur of the moment. This is not only to remove any overhead that might impede the original writers from making incremental improvements, but also for those who join the project later and want to work on the documentation.
One way to ensure basic initial documentation gets done is to limit its scope in advance. That way, writing it at least won't feel like an open-ended task. A good rule of thumb is that it should meet the following minimal criteria:
Tell the reader clearly how much technical expertise they're expected to have.
Describe clearly and thoroughly how to set up the software, and somewhere near the beginning of the documentation, tell the user how to run some sort of diagnostic test or simple command to confirm that they've set things up correctly. Startup documentation is in some ways more important than actual usage documentation. The more effort someone has invested in installing and getting started with the software, the more persistent she'll be in figuring out advanced functionality that's not well-documented. When people abandon, they abandon early; therefore, it's the earliest stages, like installation, that need the most support.
Give one tutorial-style example of how to do a common task. Obviously, many examples for many tasks would be even better, but if time is limited, pick one task and walk through it thoroughly. Once someone sees that the software can be used for one thing, they'll start to explore what else it can do on their own—and, if you're lucky, start filling in the documentation themselves. Which brings us to the next point...
Label the areas where the documentation is known to be incomplete. By showing the readers that you are aware of its deficiencies, you align yourself with their point of view. Your empathy reassures them that they don't face a struggle to convince the project of what's important. These labels needn't represent promises to fill in the gaps by any particular date —it's equally legitimate to treat them as open requests for volunteer help.
The last point is of wider importance, actually, and can be applied to the entire project, not just the documentation. An accurate accounting of known deficiencies is the norm in the open source world. You don't have to exaggerate the project's shortcomings, just identify them scrupulously and dispassionately when the context calls for it (whether in the documentation, in the bug tracking database, or on a mailing list discussion). No one will treat this as defeatism on the part of the project, nor as a commitment to solve the problems by a certain date, unless the project makes such a commitment explicitly. Since anyone who uses the software will discover the deficiencies for themselves, it's much better for them to be psychologically prepared—then the project will look like it has a solid knowledge of how it's doing.
Documentation should be available from two places: online (directly from the web site), and in the downloadable distribution of the software (see “Packaging” in Capítulo 7, Packaging, Releasing, and Daily Development). It needs to be online, in browsable form, because people often read documentation before downloading software for the first time, as a way of helping them decide whether to download at all. But it should also accompany the software, on the principle that downloading should supply (i.e., make locally accessible) everything one needs to use the package.
For online documentation, make sure that there is a link that brings up the entire documentation in one HTML page (put a note like "monolithic" or "all-in-one" or "single large page" next to the link, so people know that it might take a while to load). This is useful because people often want to search for a specific word or phrase across the entire documentation. Generally, they already know what they're looking for; they just can't remember what section it's in. For such people, nothing is more frustrating than encountering one HTML page for the table of contents, then a different page for the introduction, then a different page for installation instructions, etc. When the pages are broken up like that, their browser's search function is useless. The separate-page style is useful for those who already know what section they need, or who want to read the entire documentation from front to back in sequence. But this is not the most common way documentation is accessed. Far more often, someone who is basically familiar with the software is coming back to search for a specific word or phrase. To fail to provide them with a single, searchable document would only make their lives harder.
Developer documentation is written to help programmers understand the code, so they can repair and extend it. This is somewhat different from the developer guidelines discussed earlier, which are more social than technical. Developer guidelines tell programmers how to get along with each other; developer documentation tells them how to get along with the code itself. The two are often packaged together in one document for convenience (as with the http://subversion.apache.org/docs/community-guide/ example given earlier), but they don't have to be.
Although developer documentation can be very helpful, there's no reason to delay a release to do it. As long as the original authors are available (and willing) to answer questions about the code, that's enough to start with. In fact, having to answer the same questions over and over is a common motivation for writing documentation. But even before it's written, determined contributors will still manage to find their way around the code. The force that drives people to spend time learning a code base is that the code does something useful for them. If people have faith in that, they will take the time to figure things out; if they don't have that faith, no amount of developer documentation will get or keep them.
So if you have time to write documentation for only one audience, write it for users. All user documentation is, in effect, developer documentation as well; any programmer who's going to work on a piece of software will need to be familiar with how to use it. Later, when you see programmers asking the same questions over and over, take the time to write up some separate documents just for them.
Some projects use wikis for their initial documentation, or even as their primary documentation. In my experience, this really only works if the wiki is actively edited by a few people who agree on how the documentation is to be organized and what sort of "voice" it should have. See “Wikis” in Capítulo 3, Technical Infrastructure for more.
If the project involves a graphical user interface, or if it produces graphical or otherwise distinctive output, put some samples up on the project web site. In the case of interface, this means screenshots; for output, it might be screenshots or just files. Both cater to people's need for instant gratification: a single screenshot can be more convincing than paragraphs of descriptive text and mailing list chatter, because a screenshot is inarguable proof that the software works. It may be buggy, it may be hard to install, it may be incompletely documented, but that screenshot is still proof that if one puts in enough effort, one can get it to run.
There are many other things you could put on the project web site, if you have the time, or if for one reason or another they are especially appropriate: a news page, a project history page, a related links page, a site-search feature, a donations link, etc. None of these are necessities at startup time, but keep them in mind for the future.
There are a few sites that provide free hosting and infrastructure for open source projects: a web area, version control, a bug tracker, a download area, chat forums, regular backups, etc. The details vary from site to site, but the same basic services are offered at all of them. By using one of these sites, you get a lot for free; what you give up, obviously, is fine-grained control over the user experience. The hosting service decides what software the site runs, and may control or at least influence the look and feel of the project's web pages.
See “Canned Hosting” in Capítulo 3, Technical Infrastructure for a more detailed discussion of the advantages and disadvantages of canned hosting, and a list of sites that offer it.