POSS Chap 2 Part 1
Un article de Framalang Wiki.
[modifier] Starting From What You Have
You've looked around, found that nothing out there really fits your needs, and decided to start a new project.
What now?
The hardest part about launching a free software project is transforming a private vision into a public one. You or your organization may know perfectly well what you want, but expressing that goal comprehensibly to the world is a fair amount of work. It is essential, however, that you take the time to do it. You and the other founders must decide what the project is really about-that is, decide its limitations, what it won't do as well as what it will-and write up a mission statement. This part is usually not too hard, though it can sometimes reveal unspoken assumptions and even disagreements about the nature of the project, which is fine: better to resolve those now than later. The next step is to package up the project for public consumption, and this is, basically, pure drudgery.
What makes it so laborious is that it consists mainly of organizing and documenting things everyone already knows-"everyone ", that is, who's been involved in the project so far. Thus, for the people doing the work, there is no immediate benefit. They do not need a README file giving an overview of the project, nor a design document or user manual. They do not need a carefully arranged code tree conforming to the informal but widespread standards of software source distributions. Whatever way the source code is arranged is fine for them, because they're already accustomed to it anyway, and if the code runs at all, they know how to use it. It doesn't even matter, for them, if the fundamental architectural assumptions of the project remain undocumented; they're already familiar with that too.
Newcomers, on the other hand, need these things. Fortunately, they don't need them all at once. It's not necessary for you to provide every possible resource before taking a project public. In a perfect world, perhaps, every new Open Source project would start out life with a thorough design document, a complete user manual (with special markings for features planned but not yet implemented), beautifully and portably packaged code, capable of running on any computing platform, and so on. In reality, taking care of all these loose ends would be prohibitively time-consuming, and anyway, it's work that one can reasonably hope volunteers will help with once the project is under way.
What is necessary, however, is that enough investment be put into presentation that newcomers can get past the initial obstacle of unfamiliarity. Think of it as the first step in a bootstrapping process, to bring the project to a kind of minimum activation energy. I've heard this threshold called the hacktivation energy: the amount of energy a newcomer must put in before she starts getting something back. The lower a project's hacktivation energy, the better. Your first task is bring the hacktivation energy down to a level that encourages people to get involved.
Each of the following subsections describes one important aspect of starting a new project. They are presented roughly in the order that a new visitor would encounter them, though of course the order in which you actually implement them might be different. You can treat them as a checklist. When starting a project, just go down the list and make sure you've got each item covered, or at least that you're comfortable with the potential consequences if you've left one out.
[modifier] Commencer avec ce que vous avez
Vous avez cherché mais vous n'avez rien trouvé qui corresponde à ce dont vous avez besoin et donc vous avez décidé de commencer un nouveau projet.
Que faire maintenant?
La partie la plus difficile du lancement d'un projet de logiciel libre est la transposition d'une vision personnelle en une vision publique. Vous, ou votre organisation, savez parfaitement bien ce que vous voulez, mais exprimer ce but de manière compréhensible au monde entier représente un travail important. Il est essentiel cependant que vous preniez le temps de le faire. Vous et les autres membres fondateurs devez décider d'une définition précise du projet, c'est-à-dire, décider de ses limites, ce qu'il ne réalisera pas aussi bien que ce qu'il fera et écrire une mission. Cette partie n'est en général pas trop compliquée bien qu'elle puisse révéler des non-dits et même des désaccords à propos de la nature du projet ce qui est une bonne chose : mieux vaut résoudre ces problèmes maintenant que plus tard. L'étape suivante est de préparer la présentation du projet pour le public et c'est clairement une vraie corvée.
Ce qui rend cette étape si laborieuse est qu'elle consiste principalement à organiser et à documenter des choses que tout le monde sait déjà, « tout le monde » signifiant ici ceux qui ont déjà été impliqués dans un projet. Par conséquent, pour les gens s'occupant de cette tâche il n'y a pas de gain immédiat. Ils n'ont pas besoin de fichier « Lisez moi » décrivant le projet, ni des fiches techniques ou de la documentation utilisateur. Ils n'ont pas besoin d'une arborescence du code établie avec attention selon des standards officieux mais largement utilisés pour la distribution du code de logiciels. Peu importe comment le code source est organisé, ils s'y retrouveront, ils y sont déjà habitués de toute façon et si le code marche ils savent l'utiliser. Peu importe aussi pour eux si les bases architecturales du projet restent non documentées, ils y sont déjà familiers.
Les nouveaux arrivants, d'un autre côté, ont besoin de ces choses. Heureusement, ils n'ont pas besoin de tout, tout de suite. Il n'est pas nécessaire de donner accès à toutes les sources possibles avant de rendre le projet public. Dans un monde parfait, peut-être, chaque nouveau projet Open Source commencerait avec un modèle de document exhaustif, un manuel utilisateur complet (avec des avertissements pour les fonctionnalités prévues mais pas encore implémentées), un beau code bien assemblé et portable, capable de fonctionner sur n'importe quelle plateforme, etc. En réalité, s'occuper de tous ces détails prendrait un temps énorme et serait prohibitif et de toute façon c'est un travail pour lequel on peut espérer recevoir de l'aide de la part des volontaires une fois le projet sur les rails.
Ce qui est nécessaire cependant est de s'investir suffisamment dans la présentation pour que les débutants puissent surmonter les premiers obstacles dus à leur manque d'habitude. Il faut le voir comme le premier pas pour lancer le projet du bon pied, de lui apporter une sorte d'énergie d'activation minimale. Certains appellent ce seuil l'énergie d'hacktivation : l'énergie totale qu'un débutant doit fournir avant de recevoir quelque chose en retour. Plus l'énergie d'hacktivation du projet est basse mieux c'est. Votre première tâche sera d'abaisser cette énergie d'hacktivation à un niveau qui encourage les gens à s'engager.
Chacune des sous parties qui suivent décrit un des aspects importants du commencement d'un nouveau projet. Ils sont présentés plus ou moins dans l'ordre dans lequel un nouveau visiteur les rencontreraient, bien que l'ordre dans lequel vous les établissez puisse être différent. Vous pouvez vous en servir comme d'une checklist. Quand vous commencez un projet suivez cette liste et assurez vous que chaque point est traité ou qu'au moins vous ne soyez pas effrayé par les conséquences potentielles si vous décidez d'en laisser un de côté.
[modifier] Choose a Good Name
Put yourself in the shoes of someone who's just heard about your project, perhaps by having stumbled across it while searching for software to solve some problem. The first thing they'll encounter is the project's name.
A good name will not automatically make your project successful, and a bad name will not doom it-well, a really bad name probably could do that, but we start from the assumption that no one here is actively trying to make their project fail. However, a bad name can slow down adoption of the project, either because people don't take it seriously, or because they simply have trouble remembering it.
A good name:
* Gives some idea what the project does, or at least is related in an obvious way, such that if one knows the name and knows what the project does, the name will come quickly to mind thereafter.
- Is easy to remember. Here, there is no getting around the fact that English has become the default language of the Internet: " easy to remember " means " easy for someone who can read English to remember. " Names that are puns dependent on native-speaker pronounciation, for example, will be opaque to the many non-native English readers out there. If the pun is particularly compelling and memorable, it may still be worth it; just keep in mind that many people seeing the name will not hear it in their head the way a native speaker would.
- Is not the same as some other project's name, and does not infringe on any trademarks. This is just good manners, as well as good legal sense. You don't want to create identity confusion. It's hard enough to keep track of everything that's available on the Net already, without different things having the same name. The resources mentioned earlier in the section called "But First, Look Around" are useful in discovering whether another project already has the name you're thinking of. Free trademark searches are available at http://www.nameprotect.org/ and http://www.uspto.gov/.
- If possible, is available as a domain name in the .com, .net, and .org top-level domains. You should pick one, probably .org, to advertise as the official home site for the project; the other two should forward there and are simply to prevent third parties from creating identity confusion around the project's name. Even if you intend to host the project at some other site (see the section called "Canned Hosting"), you can still register project-specific domains and forward them to the hosting site. It helps users a lot to have a simple URL to remember.
[modifier] Choisissez un bon nom
Mettez-vous à la place de quelqu'un qui vient de découvrir votre projet, peut-être en le trouvant par hasard en cherchant un logiciel pour régler un problème. La première chose qu'il verra est le nom du projet.
Un bon nom ne fera pas automatiquement de votre projet un succès et un mauvais ne le condamne pas, enfin, un très mauvais nom peut le faire, mais nous partons de l'hypothèse que personne ici tente intentionnellement de faire échouer son projet. Quoiqu'il en soit, un mauvais nom peut ralentir l'adoption du projet soit parce que les gens ne le prennent pas au sérieux ou simplement parce qu'ils ont du mal à s'en souvenir.
Un bon nom :
- Donne une idée de ce que le projet fait, ou au moins établi clairement ce à quoi il est relié, de sorte que, pour quelqu'un qui connaît le nom et qui sait ce que le projet fait, le nom reviendra rapidement à l'esprit par la suite.
- Est simple à mémoriser. Ici vous ne pouvez pas ignorer que l'anglais est devenu le langage par défaut sur Internet: « simple à mémoriser » signifie « simple à mémoriser pour quelqu'un qui parle anglais ». Les noms qui sont des jeux de mots dépendants de la prononciation dans leur langue d'origine, par exemple, seront obscurs pour les nombreux lecteurs pour qui l'anglais n'est pas la langue maternelle. Si le jeu de mot est particulièrement bien trouvé et facile à mémoriser ça peut quand même marcher ; gardez simplement à l'esprit que de nombreuses personnes voyant le nom ne l'entendront pas dans leur tête comme une personne pour qui l'anglais est la langue maternelle.
- N'est pas le même que celui d'un autre projet et ne s'approche d'aucune marque déposée. Ce n'est que faire preuve de bonnes manières et de bon sens légal. Vous ne voulez pas créer une confusion d'identité. C'est déjà assez difficile de suivre avec tout ce qui est disponible sur le Net sans que plusieurs choses aient le même nom.
- Les sites mentionnés précédemment dans l'introduction sont d'une grande aide pour savoir si un projet a déjà adopté le nom auquel vous pensiez. Une recherche gratuite de marques déposées est également faisable sur les sites http://www.nameprotect.org/ et http://www.uspto.gov/.
- Est disponible comme nom de domaine en .com, .net ou .org si possible. Vous devriez en choisir un, vraisemblablement en .org, comme site officiel du projet pour le présenter ; les deux autres devraient renvoyer à ce premier site et sont simplement là pour éviter que quelqu'un d'autre créé une confusion d'identité autour du nom du projet. Même si vous avez l'intention d'héberger le projet sur un autre site (voir la section « Forges »), vous pouvez toujours enregistrer des noms de domaines particuliers pour le projet et les faire renvoyer vers le site d'hébergement. C'est plus pratique pour les utilisateurs d'avoir une adresse dont on se souvient facilement.
[modifier] Have a Clear Mission Statement
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.
[modifier] Définissez clairement vos objectifs
Une fois qu'ils ont trouvé le site du projet, les gens chercheront une description rapide de ce qu'il fait, l'expression de vos objectifs, afin qu'ils puissent décider rapidement (dans les 30 secondes) s'ils souhaitent en savoir plus ou pas. Cette description devrait avoir une place de choix sur la première page, préférablement juste en dessous du nom du projet.
L'expression de vos objectifs doit être concrète, restrictive et surtout concise. Voilà un bon exemple tiré du site http://www.openoffice.org/ :
Pour créer, en tant que communauté, la suite bureautique internationale dominante qui fonctionnera sur toutes les plateformes principales et qui donnera accès à toutes les fonctionnalités et à toutes les données au travers d'API basées sur des composants libres et des formats de fichier basés sur XML.
En simplement quelques mots ils ont touchés à tous les points importants, principalement en s'appuyant sur les connaissances antérieures du lecteur. En disant « en tant que communauté » ils annoncent qu'aucune société ne dominera le développement, « internationale » veut dire que les gens pourront utiliser le logiciel dans de nombreuses langues et dialectes, « toutes les plateformes principales » veut dire qu'il sera utilisable sous Unix, Macintosh et Windows. La suite annonce que l'utilisation d'interfaces ouvertes et de formats de fichiers compréhensibles est une part importante de la mission fixée. Ils ne disent pas de but en blanc qu'ils essaient de proposer une alternative libre à Microsoft Office, mais la plupart des gens peuvent le lire entre les lignes. Bien que la mission puisse paraître large au premier abord, c'est assez concis : les mots « suite bureautique » signifient quelque chose de très concret à ceux qui sont familiers avec ce genre de logiciels. Encore une fois, la connaissance présumée du lecteur (dans ce cas probablement de MS Office) est utilisée pour garder la mission concise.
La nature de la mission dépend en partie de qui l'écrit, pas uniquement du logiciel décrit. Par exemple, il est logique pour OpenOffice.org d'utiliser les mots « en tant que communauté » car le projet a été initié et est encore largement financé par Sun Microsystems. En ajoutant ces mots, Sun indique sa compréhension des craintes que la société pourrait tenter de dominer le processus de développement. En montrant simplement qu'on a conscience des conséquences possibles d'un problème on fait un grand pas en avant pour éviter complètement ce problème. D'un autre côté, les projets qui ne sont pas financés par une entreprise n'ont pas besoin de tenir un tel discours, après tout, le développement par une communauté est la norme, donc il ne devrait pas y avoir besoin de le lister parmi les objectifs.
[modifier] State That the Project is Free
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 the section called "Choosing a License and Applying It" later in this chapter, and licensing issues are discussed in detail in Chapter 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.
[modifier] Indiquez que le projet est libre
Ceux qui sont toujours intéressés après avoir lu la mission vont ensuite vouloir voir plus de détails, peut-être une documentation utilisateur ou développeur et finalement ils voudront télécharger quelque chose. Mais avant tout ça, ils voudront être sûr que c'est Open Source.
La première page doit annoncer sans ambiguïté que le projet est Open Source. Ça peut paraître évident mais vous seriez surpris de voir combien de projets oublient de le faire. J'ai vu des sites de logiciels libres où la première page non seulement ne disait pas sous quelle licence le logiciel était distribué mais ne déclarait même pas que le logiciel était libre. Parfois des informations cruciales étaient reléguées à la page Téléchargements ou à la page Développeurs ou encore dans d'autres endroits qui nécessitaient plus d'un clic pour s'y rendre. Dans les cas extrêmes, la licence n'était pas du tout mentionnée sur le site et le seul moyen de la découvrir était de télécharger le logiciel pour trouver cette information.
Ne faites pas cette erreur. Une telle omission peut vous faire perdre de nombreux développeurs et utilisateurs potentiels. Annoncez de manière claire, juste en dessous de la mission, que le projet est un « logiciel libre » ou un « logiciel Open Source » et donnez la licence exacte. Un guide rapide pour choisir la licence est donné dans la section nommée « Choisir une licence et l'appliquer » plus loin dans ce chapitre et les problèmes relatifs aux licences sont débattus plus en détails dans le Chapitre 9, Licences, droits d'auteur et brevets.
Arrivé à ce point, notre visiteur hypothétique a déterminé, probablement en une minute ou moins, s'il a envie de passer, disons, au moins cinq minutes de plus à s'informer sur le projet. La prochaine partie décrit ce qu'il devrait trouver durant ces cinq minutes.
[modifier] Features and Requirements List
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.
[modifier] Liste des fonctionnalités et pré-requis
Il devrait y avoir une brève liste des fonctionnalités proposées par le logiciel (si quelque chose n'est pas encore finalisé vous pouvez toujours le lister en ajoutant « prévu » ou « en cours » à côté) et l'environnement informatique requis pour utiliser le logiciel. Voyez la liste fonctionnalités/pré-requis comme ce que vous fourniriez à quelqu'un vous demandant un rapide résumé du logiciel. C'est souvent simplement une extension logique de la mission. Par exemple la mission pourrait être :
Pour créer un outil d'indexation de textes entiers et un moteur de recherche avec une API riche, pour l'utilisation par des programmeurs qui fournissent des services de recherche pour de grandes collections de fichiers textes.
La liste des fonctionnalités et des pré-requis donnerait des détails, clarifiant la portée de la mission.
Fonctionnalités:
- Recherche de texte brute, HTML et XML
- Recherche de mots ou de phrases
- (prévu) Correspondance approximative
- (prévu) Mise à jour incrémentale des indexes
- (prévu) Indexation de sites Web distants
Pré-requis:
- Python 2.2 ou plus récent
- Suffisamment d'espace disque pour contenir les indexes (approximativement 2x la taille d'origine des données)
Avec ces informations, les lecteurs peuvent rapidement se rendre compte si le logiciel peu ou non fonctionner pour eux et ils peuvent envisager de s'impliquer dans le développement également.
[modifier] Development Status
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 bogue 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 bogues. 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 bogueginess 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.
Alpha and Beta
The term alpha usually means a first release, with which users can get real work done and which has all the intended functionality, but which also has known bogues. The main purpose of alpha software is to generate feedback, so the developers know what to work on. The next stage, beta, means the software has had all the serious bogues fixed, but has not yet been tested enough to certify for release. The purpose of beta software is to either become the official release, assuming no bogues are found, or provide detailed feedback to the developers so they can reach the official release quickly. The difference between alpha and beta is very much a matter of judgement.
[modifier] Avancement du développement
Les gens veulent toujours savoir où en est un projet. Pour les nouveaux projets, ils veulent connaître le gap qui existe entre les promesses du projet et la réalité actuelle. Pour les projets avancés ils veulent savoir comment le projet est suivi, le rythme de sortie des nouvelles versions et sa réactivité vis-à-vis des bogues rapportés, etc.
Pour répondre à ces questions vous devriez mettre en place une page d'avancement, listant les buts à court terme du projet et ses besoins (par exemple, il pourrait être à la recherche de développeurs avec des compétences particulières). La page peut également fournir un historique des sorties passées avec une liste des fonctionnalités. Ainsi les visiteurs peuvent se faire une idée de comment le projet définit son « avancement » et sa vitesse de progression selon cette définition.
N'ayez pas peur de ne pas sembler prêt et ne céder pas à la tentation de surfaire la progression du développement. Chacun sait que le logiciel évolue par étapes, il n'y a pas de honte à dire « C'est une version alpha du logiciel avec des bogues connus. Ça fonctionne et marche au moins quelques fois, mais utilisez-le à vos propres risques ». Un tel langage ne fera pas fuir les développeurs dont vous avez besoin à cette étape. En ce qui concerne les utilisateurs, l'une des pires choses que peut faire un projet est d'attirer les utilisateurs avant que le logiciel ne soit prêt pour eux. Une image d'instabilité ou de sensibilité aux bogues est très dure à défaire une fois obtenue. Le conservatisme est rentable sur le long terme, il vaut toujours mieux pour un logiciel être plus stable que ce qu'attend l'utilisateur que le contraire, les bonnes surprises apportent un meilleur bouche à oreille.
Alpha et Bêta
Le terme alpha fait en général référence à une première version, avec laquelle les utilisateurs peuvent effectuer des tâches et qui comporte toutes les fonctionnalités prévues, mais qui également contient des bogues connus. Le but principal d'un logiciel alpha est de générer un retour, ainsi les développeurs savent sur quoi travailler. La prochaine étape, bêta, veut dire que le logiciel a été épuré des bogues les plus sérieux mais n'a pas encore été suffisamment testé pour garantir une sortie. Le but d'un logiciel bêta est soit de devenir la version officielle, si aucun bogue n'est trouvé, soit d'apporter des critiques détaillées aux développeurs pour qu'ils puissent atteindre la version finale rapidement. La différence entre alpha et bêta est principalement une question de jugement.
[modifier] Downloads
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 the section called "Release Numbering", and the details of standardizing build and installation procedures are covered in the section called "Packaging", both in Chapter 7, Packaging, Releasing, and Daily Development.
[modifier] Téléchargements
Le logiciel devrait être téléchargeable sous forme de code source dans les formats standards. Quand un projet en est à son commencement, des paquets binaires (exécutables) ne sont pas requis, à moins que la complexité de l'assemblage requis ou celle des dépendances soit telle que le simple fait de le faire marcher représenterait beaucoup de travail pour la plupart des gens. (Mais dans ce cas, il sera difficile pour le projet d'attirer des développeurs de toute façon !).
Les mécanismes de distribution devraient être aussi pratiques, standards et transparents que possible. Si vous essayiez d'éradiquer une maladie vous ne distribueriez pas un médicament de manière à ce qu'il nécessite une seringue non standard pour être administré. De la même manière, le logiciel devrait se conformer à des règles standards de construction et d'installation, plus il s'écarte des standards plus les utilisateurs et développeurs potentiels abandonneront et iront voir ailleurs, perplexes.
Ça peut sembler évident, mais de nombreux projets ne prennent pas la peine de rendre les procédures d'installation standards avant un stade avancé du développement, se disant qu'ils peuvent le faire à n'importe quel moment. « On s'occupera de tout ça quand le code sera presque fini ». Ce qu'ils ne réalisent pas c'est qu'en remettant le travail fastidieux de finition à plus tard ils rendent en fait la finalisation du code plus longue car ils découragent les développeurs qui auraient pu autrement contribuer au code. C'est même plus insidieux que cela, ils ne savent pas qu'ils perdent tous leurs développeurs, parce que ce processus est l'accumulation de non-évènements : quelqu'un visite un site Web, télécharge le logiciel, essaye de l'assembler, échoue, abandonne et va voir ailleurs. Qui saura un jour que c'est arrivé, à part la personne en question ? Personne travaillant sur le projet ne réalisera que l'intérêt de quelqu'un et sa bonne volonté ont été silencieusement gâchés.
Le travail barbant à haute rentabilité devrait toujours être réalisé tôt et faciliter significativement l'accès au projet, une bonne création de paquets est grandement payante.
Quand vous publiez un paquet téléchargeable, il est vital que vous lui attribuiez un numéro de version unique, ainsi les gens peuvent comparer deux versions et savoir laquelle est la plus récente. Une discussion détaillée à propos de la numérotation se trouve dans la section « Numérotation de version » et les détails à propos de la standardisation d'une construction et des procédures d'installation sont traités dans la section appelée « Création de Paquets », toutes les deux dans le Chapitre 7, Création de paquets, sorties et développement quotidien.
[modifier] Version Control and bogue Tracker Access
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 debogue 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 the section called "Version Control" in Chapter 3, Technical Infrastructure.
The same goes for the project's bogue tracker. The importance of a bogue tracking system lies not only in its usefulness to developers, but in what it signifies for project observers. For many people, an accessible bogue database is one of the strongest signs that a project should be taken seriously. Furthermore, the higher the number of bogues in the database, the better the project looks. This might seem counterintuitive, but remember that the number of bogues recorded really depends on three things: the absolute number of bogues present in the software, the number of users using the software, and the convenience with which those users can register new bogues. 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 bogues waiting to be discovered. The real question is, how well will the project do at recording and prioritizing those bogues? A project with a large and well-maintained bogue database (meaning bogues are responded to promptly, duplicate bogues are unified, etc.) therefore makes a better impression than a project with no bogue database, or a nearly empty database.
Of course, if your project is just getting started, then the bogue database will contain very few bogues, 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 bogue 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 bogues recorded.
Note that bogue trackers are often used to track not only software bogues, but enhancement requests, documentation changes, pending tasks, and more. The details of running a bogue tracker are covered in the section called "bogue Tracker" in Chapter 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 bogue tracker, and to make sure that fact is visible from the front page of the project.
[modifier] Gestion de configuration logicielle et accès au système de suivi de bogues
Il en va de même pour le système de suivi de bogues du projet. L'importance du suivi de bogues ne réside pas uniquement dans son utilité pour les développeurs, mais dans sa signification aux yeux des observateurs du projet. Pour beaucoup de gens, une base de données de bogues est l'un des signes les plus forts que le projet est pris au sérieux. De plus, plus il y a des bogues dans la base de données, meilleure est la santé du projet. Cela peut sembler illogique, mais souvenez-vous que le nombre de bogues enregistrés dépend principalement de trois choses : du nombre total de bogues présents dans le logiciel, du nombre de personnes utilisant le logiciel et de la facilité avec laquelle ces utilisateurs peuvent rapporter les nouveaux bogues ? De ces trois facteurs, les deux derniers sont plus importants que le premier, comment le projet va-t-il gérer l'enregistrement et la gestion des priorités de ces bogues? Un projet avec une base de données de bogues grande et développée (ce qui signifie que les bogues sont corrigés rapidement, que les bogues dupliqués sont unifiés, etc.) fait alors meilleure impression qu'un projet qui n'a pas de base de données de bogues ou qui en a une presque vide.
Bien sûr, si vous débutez juste votre projet, votre base de données contiendra très peu de bogues et vous ne pouvez pas y faire grand chose. Mais si la page d'avancement met l'accent sur la jeunesse du projet et si les gens regardant la base de données de bogues peuvent voir que la majeure partie de l'archivage a été faite récemment, ils pourront en déduire que le projet a un rythme d'archivage sain et ils ne seront pas indûment alarmés par le nombre relativement faible de bogues enregistrés.
Remarquez que les systèmes de recherche de bogues ne sont souvent pas uniquement utilisés pour rapporter les bogues du logiciel mais aussi pour rapporter les demandes d'améliorations, de modification de la documentation, des tâches en cours et plus encore. Les détails sur l'utilisation d'un système de suivi de bogues sont donnés dans la section « Système de suivi de bogues » dans le Chapitre 3, Infrastructure technique, donc je ne donnerai pas plus de précisions ici. Ce qui est important du point de vue de la présentation est simplement d'avoir un système de suivi de bogues et de vous assurez qu'il soit visible depuis la page d'accueil du projet.
[modifier] Communications Channels
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 the section called "Handling Growth" in Chapter 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.
[modifier] Les voies de communications
Les visiteurs veulent en général savoir comment contacter les êtres humains impliqués dans le projet. Fournissez les adresses des listes de diffusion, des canaux IRC et tout autre forum où chaque personne impliquée dans le logiciel peut être jointe. Indiquez clairement que vous et les autres auteurs du projets sont inscrits sur ces listes de diffusion afin que les gens puissent voir qu'il existe des moyens de donner son avis aux développeurs. Votre présence sur les listes n'implique pas que vous êtes tenus de répondre à toutes les questions ou d'ajouter toutes les idées données. Sur le long terme, la plupart des utilisateurs ne s'inscriront jamais aux forums de toute façon, mais ils seront rassurés de savoir qu'ils peuvent le faire si besoin est.
Dans les premières étapes du projet, il n'y a pas besoin de séparer les forums pour utilisateurs et ceux pour développeurs. Il vaut mieux rassembler tous ceux qui sont impliqués dans le logiciel dans une même « salle ». La distinction entre développeurs et utilisateurs est souvent floue parmi les premiers arrivants, lorsqu'elle peut être établie, le rapport du nombre de développeurs sur le nombre d'utilisateurs est en général beaucoup plus élevé dans les premiers jours du projet que plus tard. Alors que vous ne pouvez pas supposer que chaque premier venu est un programmeur qui veut taillader dans le logiciel, vous pouvez supposer qu'ils sont au minimum intéressés dans le suivi des discussions autour du développement et dans la compréhension de l'orientation du projet.
Alors que ce chapitre traite simplement de comment commencer un projet, il suffit presque de dire que ces forums de communication doivent exister. Plus tard, dans la section appelée « Gérer la croissance » dans le Chapitre 6, Communication, nous examinerons où et comment mettre en place de tels forums, dans quel mesure ils peuvent avoir besoin d'une modération ou d'autres formes de surveillance et comment séparer les forums pour utilisateurs et ceux pour développeurs quand le temps est venu sans créer un fossé infranchissable.
[modifier] Developer Guidelines
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 the section called "Writing It All Down" in Chapter 4, Social and Political Infrastructure, but the basic elements of developer guidelines are:
- pointers to forums for interaction with other developers
- instructions on how to report bogues 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://svn.collab.net/repos/svn/trunk/www/hacking.html 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 the section called "Developer documentation" later in this chapter.
[modifier] Les directives développeurs
Si une personne envisage de contribuer au projet, elle cherchera les directives développeurs. Les directives développeurs ne sont pas tellement techniques mais plutôt sociales : elles expliquent comment les développeurs interagissent entre eux et avec les utilisateurs et finalement comment les choses sont faites.
Ce sujet est détaillé dans la section appelée « Tout mettre par écrit » dans le Chapitre 4, Infrastructure sociale et politique, mais les éléments de base des directives pour les développeurs sont :
- des liens vers les forums pour l'interaction avec d'autres développeurs
- des instructions pour les rapports de bogue et la soumission de correctifs
- des indications sur la gestion du développement, le projet est-il une dictature bénévole, une démocratie ou quelque chose d'autre encore ?
Le mot « dictature » n'est pas employé dans un sens péjoratif d'ailleurs. C'est parfaitement correct de mener une tyrannie où un développeur en particulier a le droit de veto sur tous les changements. Beaucoup de projets réussis fonctionnent de cette manière. Il est simplement important d'annoncer la couleur. Une tyrannie faisant semblant d'être une démocratie découragera les gens, une tyrannie qui ne se déguise pas fonctionnera très bien tant que le tyran est compétent et a la confiance de tous.
Voir http://svn.collab.net/repos/svn/trunk/www/hacking.html pour un exemple particulièrement complet de directives pour les développeurs, ou http://www.openoffice.org/dev_docs/guidelines.html pour des directives plus larges qui se concentrent plus sur l'administration et l'esprit de participation et moins sur les aspects techniques.
Le problème distinct de la présentation du logiciel aux programmeurs est abordé dans la section appelée « Documentation développeur » plus loin dans ce chapitre.
[modifier] Documentation
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 bogue 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.
Maintaining a FAQ
A FAQ ("Frequently Asked Questions " document) can be one of the best investments a project makes in terms of educational payoff. FAQs are highly tuned to the questions users and developers actually ask-as opposed to the questions you might have expected them to ask-and therefore, a well-maintained FAQ tends to give those who consult it exactly what they're looking for. The FAQ is often the first place users look when they encounter a problem, often even in preference to the official manual, and it's probably the document in your project most likely to be linked to from other sites.
Unfortunately, you cannot make the FAQ at the start of the project. Good FAQs are not written, they are grown. They are by definition reactive documents, evolving over time in response to people's day-to-day usage of the software. Since it's impossible to correctly anticipate the questions people will ask, it is impossible to sit down and write a useful FAQ from scratch.
Therefore, don't waste your time trying to. You may, however, find it useful to set up a mostly blank FAQ template, so there will be an obvious place for people to contribute questions and answers after the project is under way. At this stage, the most important property is not completeness, but convenience: if the FAQ is easy to add to, people will add to it. (Proper FAQ maintenance is a non-trivial and intriguing problem, and is discussed more in the section called "FAQ Manager" in Chapter 8, Managing Volunteers.)
[modifier] Documentation
La documentation est essentielle. Les gens ont besoin de quelque chose à lire, même si c'est rudimentaire et incomplet. Ça tombe pile dans la catégorie « corvée », mentionnée précédemment, et c'est souvent la première étape où un nouveau projet Open Source peut s'effondrer. Proposer une mission et une liste de fonctionnalités, choisir une licence, résumer l'avancée du développement sont des tâches relativement simples qui peuvent être terminées une bonne fois pour toutes et dont vous n'aurez plus à vous soucier. La documentation, d'un autre côté, n'est jamais vraiment terminée, ce qui peut être une motivation parfois, pour certains, de retarder son exécution.
La chose la plus insidieuse est que l'utilité de la documentation pour ceux qui la rédige est le contraire de l'utilité qu'elle a pour ceux qui vont la lire. La documentation la plus importante pour les utilisateurs initiaux concerne les bases : comment rapidement mettre le logiciel en route, une vue d'ensemble de son fonctionnement et peut-être quelques guides pour accomplir des tâches courantes. Il se trouve que ce sont exactement ces choses que les auteurs de la documentation ne connaissent que trop bien, tellement bien que cela peut s'avérer difficile pour eux de voir les choses du point de vue du lecteur et d'énumérer laborieusement les étapes qui (pour les auteurs) semblent évidentes ou inutiles à mentionner.
Il n'y a pas de solution magique à ce problème. Il faut que quelqu'un prenne le temps de l'écrire et ensuite la mettre entre les mains d'un nouvel utilisateur lambda pour tester sa qualité. Utilisez un format facilement éditable comme le HTML, du texte brute, Texinfo ou une variante de XML, quelque chose qui soit pratique pour des retouches légères et des améliorations sur l'impulsion du moment. Ce n'est pas simplement pour enlever un obstacle qui pourrait gêner les auteurs qui veulent faire des améliorations, mais aussi pour ceux qui veulent rejoindre le projet par la suite et désirent travailler sur la documentation.
Une manière d'être sûr que la documentation de base sera faite est de limiter sa portée par avance. Ainsi, l'écrire ne semblera pas être une tâche sans fin. Par expérience, la documentation devrait remplir les critères minima suivant :
- Indiquer clairement au lecteur le taux d'expertise qui est attendu de sa part.
- Décrire clairement et de manière détaillée comment lancer le logiciel et, vers la fin de la documentation, dire à l'utilisateur comment faire fonctionner une sorte de diagnostic ou une commande simple pour confirmer qu'il a tout fait correctement. Les instructions de démarrage sont d'une certaine manière plus importantes que les instructions d'utilisation. Plus la personne a consenti d'efforts pour l'installation et les premiers pas avec le logiciel plus elle persistera à découvrir les fonctionnalités avancées qui ne sont pas aussi bien documentées. Quand les gens abandonnent, ils le font tôt, dans les premières étapes, comme l'installation, qui nécessitent le plus d'aide.
- Présenter un exemple, comme un tutoriel, de comment réaliser une tâche basique. Évidemment, beaucoup d'exemples pour beaucoup de tâches seraient encore mieux, mais si vous êtes limité par le temps sélectionnez une fonction et décrivez la en détails. Une fois que quelqu'un voit que le logiciel peut servir à quelque chose il va commencer à explorer les autres possibilités et compléter la documentation lui même, si vous êtes chanceux. Ce qui nous amène à....
- Indiquer les zones où la documentation n'est pas complète. En montrant au lecteur que vous êtes au courant des carences de la documentation vous vous mettez en phase avec son point de vue. Votre empathie le rassure, il n'aura pas à se battre pour convaincre le projet de ce qui est important. Ces indications n'ont pas besoin de promettre de compléter les insuffisances pour une date précise, il est légitime de les voir comme des appels à l'aide de volontaires.
Le dernier point est de plus grande importance, en fait, et peut être appliqué au projet entier, pas uniquement à la documentation. Tenir un compte précis des carences connues est la norme dans le monde de l'Open Source. Vous n'avez pas besoin d'exagérer les défauts du projet, simplement de les identifier scrupuleusement et impartialement quand le besoin s'en fait sentir (que ce soit dans la documentation, dans la base de données de suivi de bogues ou dans les discussions par la liste de diffusion). Personne ne verra cela comme du défaitisme de la part du projet, ni comme une promesse de résoudre les problèmes pour une certaine date, à moins que le projet ne s'y engage explicitement. Comme tous ceux qui utilisent le logiciel découvriront ce qui pour eux sont des carences, il est mieux qu'ils y soient préparés psychologiquement, ainsi le projet donnera l'impression de vraiment être au fait de son état de santé.
Entretenir une FAQ
Une FAQ (« Frequently Asked Questions » ou « Foire Aux Questions ») peut être l'un des meilleurs investissements du projet en terme de rentabilité en matière d'apprentissage. Les FAQ sont très liées aux questions posées par les utilisateurs et les développeurs, en opposition aux questions que vous attendiez de leur part, et donc une FAQ bien entretenue à de bonnes chances de répondre aux questions de ceux qui la consultent. La FAQ est souvent le premier document que les utilisateurs consultent lorsqu'ils ont un problème, souvent même avant le manuel officiel, et c'est sûrement le document de votre projet auquel les autres sites renverront.
Malheureusement vous ne pouvez pas créer la FAQ dès le début du projet. Les bonnes FAQ ne sont pas écrites, elles sont cultivées. Ce sont, par définition, des documents réactifs, évoluant avec le temps en réponse à l'usage quotidien des utilisateurs du logiciel. Puisqu'il n'est pas possible d'anticiper toutes les questions que les gens peuvent poser il n'est pas possible de s'asseoir et écrire une FAQ utile en partant de rien.
Par conséquent, ne gaspillez pas votre temps à essayer de le faire. Vous pourriez, par contre, trouver utile de mettre en place un modèle de FAQ vide, pour que les gens trouvent facilement un endroit où poser leurs questions et réponses une fois que le projet est sur les rails. Pour le moment, la chose la plus importante n'est pas son exhaustivité mais sa facilité d'usage : s'il est facile d'ajouter des questions/réponses à la FAQ les gens le feront (L'entretien d'une bonne FAQ est une tâche peu aisée et fascinante, on en parlera plus dans la section appelée « Responsable FAQ » dans le Chapitre 8, Gérer les volontaires).
[modifier] Availability of documentation
Documentation should be available from two places: online (directly from the Web site), and in the downloadable distribution of the software (see the section called "Packaging" in Chapter 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.
[modifier] Disponibilité de la documentation
La documentation devrait être disponible en deux endroits : en ligne, directement depuis le site Web, et dans la distribution téléchargeable du logiciel (voir la section appelée « Création de paquets » dans le Chapitre 7, Création de paquets, sorties et développement quotidien). Elle doit être en ligne, sous une forme navigable, car les gens lisent souvent la documentation avant de télécharger le logiciel pour la première fois, pour les aider à décider s'ils vont le télécharger ou pas. Mais elle doit aussi accompagner le téléchargement du logiciel qui devrait fournir (c'est-à-dire rendre l'accès hors ligne possible) tout ce dont on pourrait avoir besoin pour utiliser le paquetage.
En ce qui concerne la documentation en ligne, assurez-vous qu'il y ait un lien qui mène vers la documentation complète sur une page au format HTML (ajoutez une note comme « monolithique », « tout en un » ou « page unique » à côté du lien, afin que les gens sachent que ça pourra prendre un certain temps à charger). C'est utile car souvent ils veulent chercher un mot en particulier ou une phrase dans la documentation entière. En général ils savent déjà ce qu'ils cherchent, ils ne se souviennent simplement pas dans quelle partie se trouve l'information. Pour eux, rien n'est plus frustrant que de rencontrer une page HTML pour le sommaire, ensuite une autre pour l'introduction, une autre encore pour les instructions d'installation, etc. Quand les pages sont séparées ainsi, la fonction de recherche de leur navigateur est inutile. Une structure éclatée est utile pour ceux qui savent à quelle partie ils doivent se référer ou ceux qui veulent lire le document du début à la fin par morceaux. Ne pas leur proposer un document complet sur une seule page leur compliquerait la vie plus qu'autre chose.
[modifier] Developer documentation
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://svn.collab.net/repos/svn/trunk/www/hacking.html 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 the section called "Wikis" in Chapter 3, Technical Infrastructure for more.
[modifier] La documentation développeur
La documentation développeur est rédigée pour aider les programmeurs à comprendre le code, ainsi ils peuvent le réparer et le compléter. C'est d'une certaine manière différent des directives pour les développeurs dont nous avons parlé précédemment qui sont plus un outil social que technique. Les directives pour les développeurs indiquent aux programmeurs comment bien collaborer entre eux, la documentation développeur leur indique comment se débrouiller avec le code lui-même. Les deux sont en général groupés en un document pour des raisons pratiques (comme dans l'exemple donné plus tôt : http://svn.collab.net/repos/svn/trunk/www/hacking.html), mais ce n'est pas une obligation.
Bien que la documentation utilisateur puisse être très pratique, elle ne doit pas être la raison d'un retard de la distribution. Tant que les auteurs d'origine sont disponibles (et disposés à le faire) pour répondre aux questions à propos du code c'est déjà suffisant pour commencer. En fait, c'est le fait de devoir répondre sans cesse aux mêmes questions qui motive souvent les gens à écrire la documentation. Mais même avant qu'elle ne soit rédigée les participants motivés trouveront comment fonctionne le code. En apprenant les bases du code ils réalisent quelque chose d'utile pour eux, c'est ce qui les pousse à persévérer. Si les gens y croient vraiment ils prendront le temps de comprendre les choses, s'ils n'ont pas cette foi ce n'est pas la documentation, aussi complète puisse-t-elle être, qui les attirera ou les fera rester.
Donc si vous n'avez le temps d'écrire la documentation que pour un seul public, faites-le pour les utilisateurs. Au fond, la documentation utilisateur est également une documentation développeur puisque les programmeurs qui vont travailler sur une partie du logiciel doivent être familiers avec son utilisation. Ensuite, quand vous voyez que les programmeurs posent sans cesse les mêmes questions prenez le temps d'écrire certains documents indépendants plus spécialement pour eux.
Certains projets utilisent des wikis comme documentation de départ, ou même comme documentation principale. D'après mon expérience, ça ne fonctionne vraiment que si le wiki est souvent édité par une poignée de gens en accord sur la manière d'organiser la documentation et sur le ton qu'elle devrait avoir. Référez-vous à la section « Wikis » dans le Chapitre 3, Infrastructure technique pour en savoir plus.
[modifier] Example Output and Screenshots
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 boguegy, 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.
[modifier] Exemples de réalisations et captures d'écran
Si le projet comporte une interface graphique, s'il produit des graphiques ou tout autre forme de réalisation visible, affichez-en quelques exemples sur le site du projet. Pour les interfaces, cela signifie des captures d'écran, pour les réalisations ça pourra prendre la forme de captures d'écrans ou simplement de fichiers. Les deux satisfont le besoin des gens d'avoir une gratification immédiate : une simple capture d'écran peut se montrer plus convaincante que des paragraphes de texte descriptif et des conversations par liste de diffusion, car une capture d'écran est la preuve irréfutable que le logiciel fonctionne. Il peut être bogué, il peut être compliqué à installer, sa documentation n'est peut-être pas complète, mais cette capture d'écran est quand même la preuve que si on y met assez de bonne volonté vous pouvez le faire fonctionner.
[modifier] Screenshots
Since screenshots can be daunting until you've actually made a few, here are basic instructions for making them. Using the Gimp (http://www.gimp.org/), open File->Acquire->Screenshot, choose Single Window or Whole Screen, then click OK. Now your next mouse click will capture the window or screen clicked on as an image in the Gimp. Crop and resize the image as necessary, using the instructions at http://www.gimp.org/tutorials/Lite_Quickies/#crop.
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.
[modifier] Captures d'écran
Puisque les captures d'écran peuvent être intimidantes avant que vous n'en aillez effectivement prises quelques-unes voilà quelques instructions pour les faire. En utilisant « the Gimp » (http://www.gimp.org/), ouvrez Fichiers → Acquisition → Capture d'écran, choisissez Fenêtre simple ou Ecran entier puis faites Ok. Maintenant votre prochain clic de souris prendra une photo de la fenêtre ou de l'écran sur lequel vous cliquez sous la forme d'une image dans « the Gimp ». Coupez et re-dimensionnez l'image si nécessaire, servez vous de ces instructions si nécessaire : http://www.gimp.org/tutorials/Lite_Quickies/#crop.
Il y a bien d'autres choses que vous pouvez ajouter à votre site Web, si vous en avez le temps ou si pour une raison ou pour une autre ils vous apparaissent particulièrement appropriés : une page d'informations, une page pour l'historique du projet, une page pour les liens connexes, une fonction de recherche, un lien pour les dons, etc. Rien de tout ceci n'est absolument nécessaire au moment du lancement, mais gardez-les à l'esprit pour le futur.
[modifier] Canned Hosting
There are a few sites that provide free hosting and infrastructure for Open Source projects: a Web area, version control, a bogue 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 the section called "Canned Hosting" in Chapter 3, Technical Infrastructure for a more detailed discussion of the advantages and disadvantages of canned hosting, and a list of sites that offer it.
[modifier] Forges
Il y a quelques sites qui proposent un hébergement gratuit ainsi que l'infrastructure pour des projets Open Source : une zone Web, une gestion de configuration logicielle, un système de suivi de bogues, une zone de téléchargement, des forums de discussions, des sauvegardes régulières, etc. Les détails varient d'un site à l'autre, mais les services de base sont les mêmes partout. En utilisant l'un de ces sites vous obtiendrez beaucoup en échange de rien. Ce à quoi vous tournez le dos, évidemment, est un contrôle précis de ce que vous offrez aux utilisateurs du site. Les services d'hébergement décident des logiciels qui fonctionnent sur le site et peuvent contrôler, ou au moins influencer, l'aspect des pages Web du projet.
Je vous renvois à la section « Forges » dans le Chapitre 3, Infrastructure technique pour un exposé plus détaillé des avantages et inconvénients des forges ainsi qu'une liste de sites qui le proposent.
