POSS Chap 6 Part 4
Un article de Framalang Wiki.
Sommaire |
[modifier] Handling Growth
The price of success is heavy in the Open Source world. As your software gets more popular, the number of people who show up looking for information increases dramatically, while the number of people able to provide information increases much more slowly. Furthermore, even if the ratio were evenly balanced, there is still a fundamental scalability problem with the way most Open Source projects handle communications. Consider mailing lists, for example. Most projects have a mailing list for general user questions—sometimes the list's name is "users", "discuss", "help", or something else. Whatever its name, the purpose of the list is always the same: to provide a place where people can get their questions answered, while others watch and (presumably) absorb knowledge from observing these exchanges.
There will be no explosion when forums reach the breaking point. There is just a quiet negative feedback effect: people unsubscribe from the lists, or leave the IRC channel, or at any rate stop bothering to ask questions, because they can see they won't be heard in all the noise. As more and more people make this highly rational choice, the forum's activity will seem to stay at a manageable level. But it is staying manageable precisely because the rational (or at least experienced) people have started looking elsewhere for information—while the inexperienced people stay behind and continue posting. In other words, one side effect of continuing to use unscalable communications models as the project grows is that the average quality of both questions and answers tends to go down, which makes it look like new users are dumber than they used to be, when in fact they're probably not. It's just that the benefit/cost ratio of using those high-population forums goes down, so naturally those with the experience to do so start to look elsewhere for answers first. Adjusting communications mechanisms to cope with project growth therefore involves two related strategies:
- Recognizing when particular parts of a forum are not suffering unbounded growth, even if the forum as a whole is, and separating those parts off into new, more specialized forums (i.e., don't let the good be dragged down by the bad).
- Making sure there are many automated sources of information available, and that they are kept organized, up-to-date, and easy to find.
Strategy (1) is usually not too hard. Most projects start out with one main forum: a general discussion mailing list, on which feature ideas, design questions, and coding problems can all be hashed out. Everyone involved with the project is on the list. After a while, it usually becomes clear that the list has evolved into several distinct topic-based sublists. For example, some threads are clearly about development and design; others are user questions of the "How do I do X?" variety; maybe there's a third topic family centered around processing bug reports and enhancement requests; and so on. A given individual, of course, might participate in many different thread types, but the important thing is that there is not a lot of overlap between the types themselves. They could be divided into separate lists without causing any harmful balkanization, because the threads rarely cross topic boundaries.
Actually doing this division is a two-step process. You create the new list (or IRC channel, or whatever it is to be), and then you spend whatever time is necessary gently nagging and reminding people to use the new forums appropriately. That latter step can last for weeks, but eventually people will get the idea. You simply have to make a point of always telling the sender when a post is sent to the wrong destination, and do so visibly, so that other people are encouraged to help out with routing. It's also useful to have a Web page providing a guide to all the lists available; your responses can simply reference that Web page and, as a bonus, the recipient may learn something about looking for guidelines before posting.
Strategy (2) is an ongoing process, lasting the lifetime of the project and involving many participants. Of course it is partly a matter of having up-to-date documentation (see the section called “Documentation” in Chapter 2, Getting Started) and making sure to point people there. But it is also much more than that; the sections that follow discuss this strategy in detail.
Gérer la croissance
Le prix du succès est lourd dans le monde de l'Open Source. Au fur et à mesure que votre logiciel devient populaire le nombre de personnes cherchant des renseignements augmente de manière très importante tandis que le nombre de personnes capables de fournir ces renseignements croît bien plus lentement. De plus, même si la proportion entre les deux était à peu près équilibrée, il resterait encore un problème fondamental : l'adaptation de la gestion de la communication. Prenons les listes de diffusion par exemple. La plupart des projets disposent d'une liste pour les questions générales des utilisateurs, cette liste s'appelle parfois « utilisateurs », « discussion », « aide » ou quelque chose comme ça. Quel qu'en soit le nom, le but de cette liste est toujours le même : fournir un lieu où les gens trouvent des réponses à leurs questions, tandis que d'autres observent et (normalement) s'imprègnent des connaissances en observant ces échanges.
Il n'y a pas d'explosion quand les forums atteignent le point culminant. Il y a seulement une suite de discrets évènements néfastes : les gens se désabonnent des listes ou désertent le canal IRC ou cessent d'une manière ou d'une autre de se donner la peine de poser des questions car ils comprennent qu'ils ne seront pas entendus au milieu de tout ce bruit. Comme de plus en plus de personnes font ce choix bien compréhensible l'activité du forum semblera se maintenir à un niveau gérable. Mais elle reste gérable justement parce que les gens rationnels (ou du moins expérimentés) ont commencé à chercher l'information ailleurs, tandis que les gens inexpérimentés restent et continuent à poster. En d'autres termes, quand on continue à utiliser des modèles de communication non modulables alors que le projet grandit, l'un des effets secondaires est que la qualité moyenne des questions et des réponses tend à baisser, ce qui donne l'impression que les nouveaux utilisateurs sont plus bêtes qu'ils ne l'étaient dans le temps alors qu'en fait ce n'est probablement pas le cas. C'est juste que la rentabilité de ces forums à grande audience est plus bas, donc naturellement ceux qui en ont l'expérience s'adressent en priorité ailleurs pour obtenir leurs réponses. Ajuster les mécanismes de communication pour faire face à la croissance du projet implique deux stratégies liées :
- Identifier les parties spécifiques d'un forum qui ne subissent pas une croissance débridée, même si c'est le cas pour le forum dans son ensemble, et les détacher dans un nouveau forum plus spécialisé (c-à-d ne laissez pas le mauvais tirer le bon vers le bas.)
- S'assurer qu'il existe plusieurs sources d'information automatisées, qu'elles sont bien organisées, mises à jour et faciles à trouver.
La stratégie n°1 est généralement assez facile à mettre en œuvre. La plupart des projets démarre avec un forum principal : une liste de discussion générale dans laquelle les propositions de fonctionnalités, les questions de conception et les problèmes liés au code sont abordées en vrac. Tous les gens impliqués dans le projet y sont inscrits. Au bout d'un certain temps, il devient évident que la liste a évolué en plusieurs sous-listes orientées chacune sur un sujet. Par exemple, certains fils concernent clairement le développement et la conception ; d'autres sont des questions d'utilisateurs sur le fonctionnement « Comment faire X ? » ; une troisième lignée porte peut-être sur le traitement des rapports de bogue et les demandes d'améliorations, etc. Un individu donné peut bien sûr prendre part à plusieurs types de fils différents, mais ce qui compte est que ces catégories ne se recoupent pas trop. Ils pourraient être répartis dans des listes séparées sans causer un cloisonnement nuisible car les fils traversent rarement la frontière des sujets.
Procéder à cette division est un processus en deux étapes. On crée d'abord la nouvelle liste (ou canal IRC, ou autre), puis on passe le temps nécessaire à gentiment harceler les gens et leur rappeler l'utilisation appropriée des nouveaux forums. Cette dernière étape peut durer des semaines, mais un jour les gens s'y feront. Vous devez simplement vous astreindre à prévenir systématiquement l'expéditeur quand son message est posté au mauvais endroit, et le faire de manière visible, pour que les autres soient encouragés à vous relayer dans l'aiguillage. Il est utile également d'avoir une page Web avec un guide de toutes les listes disponibles ; vos réponses peuvent simplement renvoyer à cette page et, en prime, le destinataire aura appris à se reporter au guide d'utilisation avant de poster.
La stratégie n° 2 est un processus à long terme, qui dure tant que dure le projet et implique plusieurs participants. Bien sûr, c'est en partie une question de documentation à jour (voir la section « Documentation » du Chapitre 2, Bien démarrer) et d'orientation des gens. Mais c'est bien plus que cela. La section qui suit examine cette stratégie en détail.
[modifier] Conspicuous Use of Archives
Typically, all communications in an Open Source project (except sometimes IRC conversations) are archived. The archives are public and searchable, and have referential stability: that is, once a given piece of information is recorded at a particular address, it stays at that address forever.
Use those archives as much as possible, and as conspicuously as possible. Even when you know the answer to some question off the top of your head, if you think there's a reference in the archives that contains the answer, spend the time to dig it up and present it. Every time you do that in a publicly visible way, some people learn for the first time that the archives are there, and that searching in them can produce answers. Also, by referring to the archives instead of rewriting the advice, you reinforce the social norm against duplicating information. Why have the same answer in two different places? When the number of places it can be found is kept to a minimum, people who have found it before are more likely to remember what to search for to find it again. Well-placed references also contribute to the quality of search results in general, because they strengthen the targeted resource's ranking in Internet search engines.
There are times when duplicating information makes sense, however. For example, suppose there's a response already in the archives, not from you, saying:
It appears that your Scanley indexes have become frobnicated. To unfrobnicate them, run these steps:
1. Shut down the Scanley server. 2. Run the 'defrobnicate' program that ships with Scanley. 3. Start up the server.
Then, months later, you see another post indicating that someone's indexes have become frobnicated. You search the archives and come up with the old response above, but you realize it's missing some steps (perhaps by mistake, or perhaps because the software has changed since that post was written). The classiest way to handle this is to post a new, more complete set of instructions, and explicitly obsolete the old post by mentioning it:
It appears that your Scanley indexes have become frobnicated. We saw this problem back in July, and J. Random posted a solution at http://blahblahblah/blah. Below is a more complete description of how to unfrobnicate your indexes, based on J. Random's instructions but extending them a bit:
- Shut down the Scanley server.
- Become the user the Scanley server normally runs as.
- As that user, run the 'defrobnicate' program on the indexes.
- Run Scanley by hand to see if the indexes work now.
- Restart the server.
(In an ideal world, it would be possible to attach a note to the old post, saying that there is newer information available and pointing to the new post. However, I don't know of any archiving software that offers an "obsoleted by" feature, perhaps because it would be mildly tricky to implement in a way that doesn't violate the archives' integrity as a verbatim record. This is another reason why creating dedicated Web pages with answers to common questions is a good idea.)
Archives are probably most often searched for answers to technical questions, but their importance to the project goes well beyond that. If a project's formal guidelines are its statutory law, the archives are its common law: a record of all decisions made and how they were arrived at. In any recurring discussion, it's pretty much obligatory nowadays to start with an archive search. This allows you to begin the discussion with a summary of the current state of things, anticipate objections, prepare rebuttals, and possibly discover angles you hadn't thought of. Also, the other participants will expect you to have done an archive search. Even if the previous discussions went nowhere, you should include pointers to them when you re-raise the topic, so people can see for themselves a) that they went nowhere, and b) that you did your homework, and therefore are probably saying something now that has not been said before.
Utilisation visible des archives
Traditionnellement, toutes les communications échangées dans un projet Open Source (exceptées parfois les conversations IRC) sont archivées. Les archives sont publiques et consultables et elles ont une stabilité référentielle : c'est-à-dire qu'une fois qu'une information a été enregistrée à une adresse donnée, elle y reste pour toujours.
Utilisez ces archives autant que possible et aussi visiblement que possible. Même si vous connaissez par cœur la réponse à une question, si vous pensez qu'il y a dans les archives une référence qui contient la réponse, prenez le temps d'aller la chercher et de la montrer. Chaque fois que vous faites ceci publiquement et de manière visible, quelqu'un apprend pour la première fois que les archives sont là et qu'elles contiennent des réponses aux questions. De même, en vous référant aux archives plutôt qu'en ré-écrivant la réponse, vous renforcez la règle sociale qui lutte contre la duplication de l'information. Pourquoi avoir la même réponse à deux endroits différents ? Les gens retrouveront plus facilement une réponse qu'ils ont déjà dénichée si celle-ci n'est pas répliquée x fois. Des références faciles à localiser contribuent également à la qualité des résultats des recherches en général car elles renforcent la classification des ressources ciblées par les moteurs de recherche Internet.
Il existe pourtant des cas où dupliquer l'information peut avoir un sens. Imaginez par exemple qu'il y a déjà une réponse dans les archives, pas de vous, qui dit :
Il s'avère que vos index de Scanley ont été embrouillés. Pour les désembrouiller, suivez les étapes suivantes :
- Eteignez le serveur Scanley.
- Lancez le programme "désembrouillage" livré avec Scanley.
- Redémarrez le serveur.
Puis, des mois plus tard, vous verrez un autre message expliquant que les index de quelqu'un ont été embrouillés. Vous cherchez dans les archives et trouvez l'ancienne réponse ci-dessus, mais vous vous rendez compte qu'il y manque quelques étapes (soit par erreur, soit parce que le logiciel a changé depuis la rédaction du message). La meilleure façon de procéder consiste à poster de nouvelles instructions, plus complètes, et de rendre explicitement obsolète le message précédent en le mentionnant :
Il s'avère que vos index de Scanley ont été embrouillés. Nous avons vu ce problème en juillet dernier et A. Nonyme avait posté une solution à l'adresse http://blablabla/bla. Vous trouverez ci-dessous des indications plus complètes pour désembrouiler vos index, basées sur celles de A. Nonyme mais un peu plus développées :
- Eteignez le serveur Scanley
- Devenez l'utilisateur habituellement connecté au serveur Scanley
- Sous ce nom d'utilisateur, lancez le programme « désembrouillage » dans les index
- Lancez Scanley à la main pour voir si les index fonctionnent
- Redémarrez le serveur
(Dans un monde idéal, il serait possible d'attacher une note à l'ancien message précisant qu'il y a des informations plus récentes et pointant vers le nouvel article. Cependant, je ne connais aucun logiciel d'archivage qui propose une fonction « rendu obsolète par », peut-être parce qu'il serait difficile à mettre en oeuvre de façon à ce que l'intégrité des archives soit préservée en tant que trace verbatim. C'est là une autre raison qui justifie la création de pages Web dédiées consignant les réponses aux questions courantes.)
Les archives sont le plus souvent utilisées pour chercher des réponses aux questions techniques, mais leur importance pour le projet va au-delà. Si les règles d'utilisation formelles du projet constituent la loi ordinaire, les archives représentent le droit coutumier : des archives de toutes les décisions prises et de comment on y est parvenu. Dans toute discussion récurrente il est plus ou moins obligatoire de nos jours de commencer par une recherche dans les archives. Ceci permet de commencer la discussion par une résumé de l'état actuel des choses, d'anticiper des objections, de parer aux réticences et probablement de trouver des idées auxquelles vous n'auriez pas pensé. Du point de vue des autres participants aussi vous êtes censé avoir fait une recherche dans les archives. Même si les discussions précédentes n'ont mené nulle part vous devriez mettre un lien qui y renvoi au moment de remettre la question sur le tapis pour que les gens constatent par eux-mêmes que : a) elles n'ont mené nulle part et b) vous avez fait votre boulot. Ils seront alors en mesure de dire quelque chose qui n'a pas été dit auparavant.
[modifier] Treat all resources like archives
All of the preceding advice applies to more than just mailing list archives. Having particular pieces of information at stable, conveniently findable addresses should be an organizing principle for all of the project's information. Let's take the project FAQ as a case study.
How do people use a FAQ?
- They want to search in it for specific words and phrases.
- They want to browse it, soaking up information without necessarily looking for answers to specific questions.
- They expect search engines such as Google to know about the FAQ's content, so that searches can result in FAQ entries.
- They want to be able to refer other people directly to specific items in the FAQ.
- They want to be able to add new material to the FAQ, but note that this happens much less often than answers are looked up—FAQs are far more often read from than written to.
Traitez toutes les ressources comme des archives
Tous les conseils précédents ne s'appliquent pas qu'aux archives des listes de diffusion. Certaines informations doivent être enregistrées à des adresses stables, faciles à trouver. Ceci devrait être un principe en vigueur pour toute information concernant le projet. Prenons la FAQ du projet comme cas d'étude.
Comment les gens utilisent-ils une FAQ ?
- Ils veulent pouvoir y chercher des mots et des phrases
- Ils veulent pouvoir la parcourir, aller à la pêche aux informations sans chercher nécessairement de réponses à des questions spécifiques
- Ils s'attendent à ce que le contenu de la FAQ soit accessible aux moteurs de recherche tel que Google, de façon à ce que les recherches pointent vers les rubriques de la FAQ
- Ils veulent pouvoir indiquer à d'autres personnes des articles spécifiques de la FAQ
- Ils veulent pouvoir ajouter de nouveaux éléments à la FAQ. Notez néanmoins que ceci est bien moins courant que la recherche de réponses : on lit plus souvent une FAQ qu'on y écrit
Named Anchors and ID Attributes
There are two ways to get a browser to jump to a specific location within a Web page: named anchors and id attributes.
A named anchor is just a normal HTML anchor element (<a>...</a>), but with a "name" attribute:
<a name="mylabel">...</a>
More recent versions of HTML support a generic id attribute, which can be attached to any HTML element, not just to <a>. For example:
<p id="mylabel">...</p>
Both named anchors and id attributes are used in the same way. One appends a hash mark and the label to a URL, to cause the browser to jump straight to that spot in the page:
http://myproject.example.com/faq.html#mylabel
Virtually all browsers support named anchors; most modern browsers support the id attribute. To play it safe, I would recommend using either named anchors alone, or named anchors and id attributes together (with the same label for both in a given pair, of course). Named anchors cannot be self-closing—even if there's no text inside the element, you must still write it in two-sided form:
<a name="mylabel"></a>
...though normally there would be some text, such as the title of a section.
Whether you use a named anchor, or an id attribute, or both, remember that the label will not be visible to someone who browses to that location without using the label. But such a person might want to discover the label for a particular location, so they can mail the URL for a FAQ answer to a friend, for example. To help them do this, add a title attribute to the same element(s) where you added the "name" and/or "id" attribute, for example:
<a name="mylabel" title="#mylabel">...</a>
When the mouse pointer is held over the text inside the title-attributed element, most browsers will pop up a tiny box showing the title. I usually include the hash-sign, to remind the user that this is what she would put at the end of the URL to jump straight to this location next time.
Formatting the FAQ like this is just one example of how to make a resource presentable. The same properties—direct searchability, availability to major Internet search engines, browsability, referential stability, and (where applicable) editability—apply to other Web pages, the source code tree, the bug tracker, etc. It just happens that most mailing list archiving software long ago recognized the importance of these properties, which is why mailing lists tend to have this functionality natively, while other formats may require some extra effort on the maintainer's part (Chapter 8, Managing Volunteers discusses how to spread that maintenance burden across many volunteers).
Ancres nommées (named anchors) et attributs ID
Il existe deux solutions pour qu'un navigateur se place à un endroit précis d'une page Web : les ancres nommées et les attributs ID.
Une ancre nommée n'est qu'une ancre html normale (<a>...</a>), à laquelle on attribue un « nom » :
<a name="monetiquette">...</a>
Des versions plus récentes de HTML supportent un attribut id générique qui peut être attaché à n'importe quel élément HTML et pas seulement à <a>. Par exemple :
<p id="monetiquette">...</p>
Ancres nommées et attributs id sont utilisés de la même façon. On fait suivre l'URL d'un dièse et de l'étiquette pour que le navigateur aille directement à cet endroit de la page :
http://monprojet.exemple.com/faq.html#monetiquette
Théoriquement tous les navigateurs supportent les ancres nommées ; les plus récents supportent les attributs id. Par prudence, je recommande soit de n'utiliser que des ancres nommées, soit des ancres nommées et des attributs id ensemble (avec la même étiquette pour les deux, évidemment). Les ancres nommées ne sont pas auto-fermantes : même s'il n'y a pas de texte à l'intérieur de l'élément, il faut l'écrire en deux parties :
<a name="monetiquette"></a>
...bien que normalement il devrait y avoir un texte, comme un titre de section.
Que vous utilisiez une ancre nommée, un attribut id ou les deux, rappelez-vous que ne sera pas visible à ceux qui parcourent la page sans utiliser l'étiquette. Mais cette personne peut vouloir connaître l'étiquette d'une section en particulier, pour pouvoir envoyer l'URL de la réponse de la FAQ à un ami par exemple. Pour l'y aider, ajoutez un titre aux éléments auxquels vous avez ajouté un « nom » et/ou un « id », par exemple :
<a name="monetiquette" title="#monetiquette">...</a>
En plaçant le pointeur de la souris sur le texte qui se trouve à l'intérieur de l'attribut « title », la plupart des navigateurs ouvriront une petit fenêtre où s'affiche le titre. J'ajoute généralement le dièse pour rappeler à l'utilisateur que c'est le symbole qu'il devra ajouter à la fin de l'URL pour aller directement à cet endroit la prochaine fois.
Ce n'est qu'un exemple de mise en page de la FAQ qui permet d'en faire un ressource présentable. Les mêmes propriétés, accès direct lors de la recherche, accessibilité aux principaux moteurs de recherche Internet, navigabilité, stabilité du référentiel et, le cas échéant, capacité d'édition s'appliquent également à d'autres pages Web, à l'arborescence du code source, au système de suivi de bogues, etc. Il se trouve que la plupart des logiciels d'archivage des listes de diffusion ont reconnu depuis longtemps l'importance de ces propriétés, c'est pourquoi les listes ont tendance à inclure ces fonctions de manière native alors que d'autres formats exigent un effort supplémentaire de la part de celui qui est chargé de leur maintenance (le Chapitre 8, Gérer les volontaires examine comment distribuer la charge de cette maintenance entre plusieurs volontaires).
[modifier] Codifying Tradition
As a project acquires history and complexity, the amount of data each incoming participant must absorb increases. Those who have been with the project a long time were able to learn, and invent, the project's conventions as they went along. They will often not be consciously aware of what a huge body of tradition has accumulated, and may be surprised at how many missteps recent newcomers seem to make. Of course, the issue is not that the newcomers are of any lower quality than before; it's that they face a bigger acculturation burden than newcomers did in the past.
The traditions a project accumulates are as much about how to communicate and preserve information as they are about coding standards and other technical minutiae. We've already looked at both sorts of standards, in the section called “Developer documentation” in Chapter 2, Getting Started and the section called “Writing It All Down” in Chapter 4, Social and Political Infrastructure respectively, and examples are given there. What this section is about is how to keep such guidelines up-to-date as the project evolves, especially guidelines about how communications are managed, because those are the ones that change the most as the project grows in size and complexity.
First, watch for patterns in how people get confused. If you see the same situations coming up over and over, especially with new participants, chances are there is a guideline that needs to be documented but isn't. Second, don't get tired of saying the same things over and over again, and don't sound like you're tired of saying them. You and other project veterans will have to repeat yourselves often; this is an inevitable side effect of the arrival of newcomers.
Every Web page, every mailing list message, and every IRC channel should be considered advertising space—not for commercial advertisements, but for ads about your project's own resources. What you put in that space depends on the demographics of those likely to read it. An IRC channel for user questions, for example, is likely to get people who have never interacted with the project before—often someone who has just installed the software, and has a question he'd like answered immediately (after all, if it could wait, he'd have sent it to a mailing list instead, which would probably use less of his total time, although it would take longer for an answer to come back). People usually don't make a permanent investment in the IRC channel; they'll show up, ask their question, and leave.
Therefore, the channel topic should be aimed at people looking for technical answers about the software right now, rather than at, say, people who might get involved with the project in a long term way and for whom community interaction guidelines might be more appropriate. Here's how a really busy channel handles it (compare this with the earlier example in the section called “IRC / Real-Time Chat Systems” in Chapter 3, Technical Infrastructure):
- You are now talking on #linuxhelp
- Topic for #linuxhelp is Please READ
- http://www.catb.org/~esr/faqs/smart-questions.html &&
- http://www.tldp.org/docs.html#howto BEFORE asking questions | Channel
- rules are at http://www.nerdfest.org/lh_rules.html | Please consult
- http://kerneltrap.org/node/view/799 before asking about upgrading to a
- 2.6.x kernel | memory read possible: http://tinyurl.com/4s6mc ->
- update to 2.6.8.1 or 2.4.27 | hash algo disaster: http://tinyurl.com/6w8rf
- | reiser4 out
With mailing lists, the "ad space" is a tiny footer appended to every message. Most projects put subscription/unsubscription instructions there, and perhaps a pointer to the project's home page or FAQ page as well. You might think that anyone subscribed to the list would know where to find those things, and they probably do—but many more people than just subscribers see those mailing list messages. An archived post may be linked to from many places; indeed, some posts become so widely known that they eventually have more readers off the list than on it.
Formatting can make a big difference. For example, in the Subversion project, we were having limited success using the bug-filtering technique described in the section called “Pre-Filtering the Bug Tracker” in Chapter 3, Technical Infrastructure. Many bogus bug reports were still being filed by inexperienced people, and each time it happened, the filer had to be educated in exactly the same way as the 500 people before him. One day, after one of our developers had finally gotten to the end of his rope and flamed some poor user who didn't read the issue tracker guidelines carefully enough, another developer decided this pattern had gone on long enough. He suggested that we reformat the issue tracker front page so that the most important part, the injunction to discuss the bug on the mailing lists or IRC channels before filing, would stand out in huge, bold red letters, on a bright yellow background, centered prominently above everything else on the page. We did so (you can see the results at http://subversion.tigris.org/project_issues.html), and the result was a noticeable drop in the rate of bogus issue filings. We still get them, of course—we always will—but the rate has slowed considerably, even as the number of users increases. The outcome is not only that the bug database contains less junk, but that those who respond to issue filings stay in a better mood, and are more likely to remain friendly when responding to one of the now-rare bogus filings. This improves both the project's image and the mental health of its volunteers.
The lesson for us was that merely writing up the guidelines was not enough. We also had to put them where they'd be seen by those who need them most, and format them in such a way that their status as introductory material would be immediately clear to people unfamiliar with the project.
Static Web pages are not the only venue for advertising the project's customs. A certain amount of interactive policing (in the friendly-reminder sense, not the handcuffs-and-jail sense) is also required. All peer review, even the commit reviews described in the section called “Practice Conspicuous Code Review” in Chapter 2, Getting Started, should include review of people's conformance or non-conformance with project norms, especially with regard to communications conventions.
Another example from the Subversion project: we settled on a convention of "r12908" to mean "revision 12908 in the version control repository." The lower-case "r" prefix is easy to type, and because it's half the height of the digits, it makes an easily-recognizable block of text when combined with the digits. Of course, settling on the convention doesn't mean that everyone will begin using it consistently right away. Thus, when a commit mail comes in with a log message like this:
------------------------------------------------------------------------ r12908 | qsimon | 2005-02-02 14:15:06 -0600 (Wed, 02 Feb 2005) | 4 lines Patch from J. Random Contributor <jrcontrib@gmail.com> * trunk/contrib/client-side/psvn/psvn.el: Fixed some typos from revision 12828. ------------------------------------------------------------------------
...part of reviewing that commit is to say "By the way, please use 'r12828', not 'revision 12828' when referring to past changes." This isn't just pedantry; it's important as much for automatic parsability as for human readership.
By following the general principle that there should be canonical referral methods for common entities, and that these referral methods should be used consistently everywhere, the project in effect exports certain standards. Those standards enable people to write tools that present the project's communications in more useable ways—for example, a revision formatted as "r12828" could be transformed into a live link into the repository browsing system. This would be harder to do if the revision were written as "revision 12828", both because that form could be divided across a line break, and because it's less distinct (the word "revision" will often appear alone, and groups of numbers will often appear alone, whereas the combination "r12828" can only mean a revision number). Similar concerns apply to issue numbers, FAQ items (hint: use a URL with a named anchor, as described in Named Anchors and ID Attributes), etc.
Even for entities where there is not an obvious short, canonical form, people should still be encouraged to provide key pieces of information consistently. For example, when referring to a mailing list message, don't just give the sender and subject; also give the archive URL and the Message-ID header. The last allows people who have their own copy of the mailing list (people sometimes keep offline copies, for example to use on a laptop while traveling) to unambiguously identify the right message even if they don't have access to the archives. The sender and subject wouldn't be enough, because the same person might make several posts in the same thread, even on the same day.
The more a project grows, the more important this sort of consistency becomes. Consistency means that everywhere people look, they see the same patterns being followed, so they know to follow those patterns themselves. This, in turn, reduces the number of questions they need to ask. The burden of having a million readers is no greater than that of having one; scalability problems start to arise only when a certain percentage of those readers ask questions. As a project grows, therefore, it must reduce that percentage by increasing the density and accessibility of information, so that any given person is more likely to find what he needs without having to ask.
Codifier la tradition
Quand l'histoire d'un projet s'étoffe et gagne en complexité, la quantité de données que chaque nouvel arrivant doit assimiler augmente. Ceux qui participent au projet depuis longtemps ont pu apprendre, voire forger, les conventions du projet en cours de route. Très souvent, ils n'auront pas clairement conscience du corpus de traditions qui s'est accumulé et seront surpris des nombreux impairs que les nouveaux sont susceptibles de commettre. Bien sûr, le problème n'est pas que les nouveaux venus sont moins bien qu'avant ; c'est que l'effort d'acclimatation qu'ils doivent consentir est plus important que pour les nouveaux venus d'avant.
Les traditions qu'un projet accumule portent aussi bien sur la communication et la préservation de l'information que sur la qualité du code ou d'autres détails techniques. Nous avons déjà examiné ces deux types de mesures respectivement dans la section « Documentation développeur » du Chapitre 2 et dans la section intitulée « Tout mettre par écrit » du Chapitre 4 où des exemples ont été fournis. Cette partie se concentre plus sur le maintien de ces guides d'utilisation à jour avec l'évolution du projet, plus particulièrement le guide concernant la gestion des communications, car c'est ce qui change le plus quand le projet croît en taille et en complexité.
Premièrement, cherchez ce qui est le plus déroutant pour les gens. Si vous voyez les mêmes situations revenir sans cesse, particulièrement avec les nouveaux participants, il y a des chances que le guide ne soit pas documenté. Deuxièmement, ne vous lassez pas de répéter cent fois les mêmes choses et n'ayez pas l'air las en les répétant. Vous, ainsi que les autres vétérans du projet, aurez à vous répéter souvent ; c'est un effet secondaire inévitable généré par l'arrivée de nouveaux.
Chaque page Web, chaque message de la liste, chaque canal IRC doivent être considérés comme des espaces publicitaires : non pas pour passer des annonces commerciales, mais pour faire la réclame des ressources propres au projet. Ce que vous mettrez dans chaque espace dépend de la population susceptible de le lire. Un canal IRC consacré aux questions des utilisateurs, par exemple, amènera des gens qui n'ont jamais été en relation avec le projet auparavant, généralement quelqu'un qui vient d'installer le logiciel et qui aimerait une réponse immédiate à sa question (après tout, si ça pouvait attendre, il l'aurait postée sur la liste de diffusion, ce qui lui prendrait probablement moins de temps dans l'ensemble, bien que le délai pour la réponse soit plus long). Les gens n'investissent généralement pas le canal IRC sur la durée : ils surgissent, posent leur question et s'en vont.
C'est pourquoi le sujet du canal doit viser les gens qui cherchent des réponses techniques sur le logiciel de manière immédiate, plutôt que, disons, des gens qui pourraient s'investir dans le projet à long terme et pour qui le manuel des usages de la communauté serait plus approprié. Voici comment un canal réellement actif gère la question (à comparer avec l'exemple précédent dans la section « IRC et les chats en temps réel » du Chapitre 3, Infrastructure Technique) :
- Vous êtes actuellement sur #linuxhelp
- Le sujet de #linuxhelp est SVP lisez
- http://www.catb.org/~esr/faqs/smart-questions.html et
- http://www.tldp.org/docs.html#howto AVANT de poser une question | Les règles
- du canal se trouvent ici : http://www.nerdfest.org/lh_rules.html | Veuillez consulter
- http://kerneltrap.org/node/view/799 avant de poser une question
- sur la mise à jour en 2.6.x | aide mémoire : http://tinyurl.com/4s6mc ->
- mise à jour 2.6.8.1 ou 2.4.27 | sinistre algorithme de hachage : http://tinyurl.com/6w8rf
- | reiser4 out
Dans les listes de diffusion, l'« espace publicitaire » consiste en un pied de page (footer) ajouté à la fin de chaque message. La plupart des projets y font figurer les instructions pour s'inscrire/se désinscrire ainsi qu'éventuellement un lien vers la page d'accueil du projet ou vers la FAQ. Vous pensez peut-être que tous les abonnés de la liste savent où trouver ces informations, et c'est vraisemblablement le cas, mais bien des personnes autres que les abonnés voient les messages de la liste. Des liens peuvent pointer vers le courrier archivé depuis de multiples endroits ; de fait, certains messages deviennent si connus qu'ils peuvent avoir plus de lecteurs hors liste que dans la liste.
Le formatage peut apporter un réel plus. Par exemple, dans le projet Subversion nous avions un succès limité avec l'utilisation de la technique de filtrage de bogues décrite dans la section « Filtrer le système de suivi des bogues en amont » du Chapitre 3, Infrastructure technique. De nombreux rapports de bogues bidons étaient créés par des gens inexpérimentés et, chaque fois que cela se produisait, il fallait former le rapporteur exactement de la même manière que les 500 rapporteurs précédents. Un jour, alors qu'un de nos développeurs avait fini par perdre patience et s'en était pris à un pauvre utilisateur qui n'avait pas lu assez attentivement le manuel du traqueur de bogues un autre développeur décida qu'il était temps de mettre fin à ce schéma. Il proposa une refonte de la page d'accueil du traqueur de bogues pour faire ressortir en gros caractères rouge et gras sur fonds jaune, bien centrés en tête de page, le point le plus important, à savoir l'incitation à discuter le bogue sur la liste de diffusion et sur le canal IRC avant de remplir un rapport. Ce qui fut fait (vous pouvez voir le résultat sur http://subversion.tigris.org/project_issues.html). Il en résulta une baisse notable du nombre de rapports de bogues bidons. Nous en recevons encore bien sûr, nous en recevrons toujours, mais le taux a baissé considérablement et ce malgré l'augmentation du nombre d'utilisateurs. En conséquence, non seulement notre base de données contient moins de déchets, mais ceux qui travaillent à résoudre les bogues conservent leur bonne humeur et ont plus de chances de rester aimables au moment de répondre à l'un de ces rares rapports bidons. L'image du projet n'en est que meilleure et la santé mentale des volontaires est épargnée.
La leçon que nous en avons tirée est qu'il ne suffit pas simplement de mettre les règles par écrit. Il faut également les rendre visibles à ceux qui en ont le plus besoin et les présenter de telle sorte que leur rôle de support d'introduction au projet soit suffisamment clair pour ceux qui ne connaissaient pas le projet.
Des pages Web statiques ne sont pas le seul espace pour promouvoir les us et coutumes du projet. Une certaine dose de surveillance interactive (dans le sens de « rappel amical » plutôt que de « mettre à l'amende ») est également nécessaire. Toute révision par les pairs, y compris les révisions de commit décrites dans la section intitulée « Effectuez une inspection visible du code » du Chapitre 2, Bien démarrer, devraient inclure le passage en revue de la conformité ou non conformité aux normes, notamment en ce qui concerne les conventions de communication.
Voici un autre exemple tiré du projet Subversion : nous avons fixé par convention que « r12908 » signifait « révision 12908 dans le dépôt de gestion de version ». Le préfixe en bas de casse « r » est facile à taper et sa taille étant moitié moindre que celle des chiffres on obtient un bloc de texte facilement reconnaissable. Bien sûr, le fait de fixer cette convention n'implique pas que tout le monde va l'utiliser immédiatement et uniformément. Ainsi, quand arrive un message de commit avec un message du fichier journal comme celui-ci :
------------------------------------------------------------------------ r12908 | qsimon | 2005-02-02 14:15:06 -0600 (Wed, 02 Feb 2005) | 4 lines Correctif de A. Nonyme <anonyme@gmail.com> * trunk/contrib/client-side/psvn/psvn.el: Corrigé quelques typos sur la révision 12828. ------------------------------------------------------------------------
...la relecture de ce commit comprend également un petit mot du genre : "« Au fait, utilisez de préférence 'r12828' au lieu de 'révision 12828' pour parler des changements précédents. » Ce n'est pas juste de la pédanterie : c'est aussi important pour l'indexation automatique que pour la lisibilité humaine.
En suivant le principe général selon lequel il devrait y avoir une méthode étalon de référence pour des unités communes et que ces méthodes de référence devraient être utilisées partout uniformément, le projet exporte de manière effective certaines normes. Ces normes permettent aux gens d'écrire des outils qui permettent de présenter les échanges du projet sous une forme plus exploitable. Une révision sous la forme « r12828 » peut être transformée en lien vivant dans le système de navigation du dépôt par exemple. Ceci serait plus difficile à faire si la révision avait été notée sous la forme « révision 12828 », d'une part parce que cette expression aurait pu être divisée par un retour à la ligne et d'autre part parce qu'elle est moins distincte (le mot révision, avec ou sans accent, apparaîtra souvent isolé des chiffres, tandis que la combinaison « r12828 » ne peut que signifier « numéro de révision »). Des problèmes similaires se posent pour les numéros d'émissions, les points de la FAQ (une piste : utilisez des URL avec des ancres nommées, comme indiqué dans « Ancres nommées et attributs ID »), etc.
Même pour les unités où il n'y a pas d'étalon défini les gens devraient être encouragés à fournir les informations clés de manière uniformisée. Par exemple pour vous référer à un message d'une liste de diffusion ne mentionnez pas seulement l'émetteur et le sujet : citez également l'URL de l'archive et le Message-ID de l'en-tête. Ce dernier permet à ceux qui ont leur propre copie de la liste de diffusion (certaines personnes conservent une copie hors ligne, pour l'utiliser sur un portable lors d'un voyage par exemple) d'identifier univoquement le message même s'ils n'ont pas accès aux archives. L'émetteur et le sujet ne suffisent pas car la même personne peut avoir posté plusieurs fois le même jour dans le même fil.
Plus un projet grandit plus cette uniformité devient importante. Uniformité signifie que, quel que soit l'endroit, les mêmes règles sont appliquées, ce qui incite les gens à suivre ces mêmes règles. Ceci, en retour, réduit le nombre de questions qu'ils ont à poser. La charge d'avoir un million de lecteurs n'est pas plus grande que celle d'en avoir un ; les problèmes d'échelle commencent à se poser seulement quand un certain pourcentage de ces lecteurs posent des questions. Quand le projet grandit il faut donc réduire ce pourcentage en augmentant la densité et l'accessibilité de l'information pour que chaque personne ait plus de chance de trouver ce dont elle a besoin sans avoir à le demander.
- qui dit mieux pour "frobnicate" ? apparemment ça tient du tripotage et du brouillage. Merci de vérifier ce passage.
- "self-closing", en parlant des ancres nommées : auto-fermantes ?
- live link : lien vivant ?
