Du libre au service du libre

[Epeios]

Voilà plus de cinq ans, j'ai crée un site Web dédié au projet Epeios (http://epeios.org/), projet proposant des bibliothèques C++ multi-fonctions et portables, disponibles sous licence GNU GPL. Seulement voilà, son auteur mis à part, ce projet ne bénéficie à personne, bien que ce soit un projet se réclamant du Logiciel Libre (pour preuve, son CVS est hébergé sur le serveur Savannah du projet GNU).

En visitant le site en question, il vous apparaîtra clairement que le problème réside dans la documentation, autant dans son aspect qualitatif que quantitatif. Ce problème trouve sa source dans le fait que je n'ai (entre autres) ni le talent, ni les compétences, ni d'ailleurs la motivation nécessaires pour rédiger une documentation digne de ce nom. De plus, étant impliqué dans ce projet en tant que (unique) développeur de ces bibliothèques, il m'est difficile d'avoir le recul nécessaire à la rédaction d'une documentation à destination de néophytes.

Ces derniers temps, de nombreux outils pour le Web sont apparus, et je me suis demandé dans quelle mesure ces outils pourraient contribuer à résoudre le problème en question. Utilisant quotidiennement les bibliothèques Epeios, je pourrais, par exemple, rendre compte, à l'aide d'un wiki, de la manière dont j'utilise ces bibliothèques. Une sorte de pense-bête, qu'il me sera facile d'enrichir et de faire évoluer grâce à la souplesse d'utilisation propre à tout wiki.

Avec le temps, je finirais par couvrir un nombre suffisamment important de fonctionnalités pour susciter quelqu'intérêt de la part des visiteurs. Cet intérêt se manifestera sans doute d'abord par des questions/remarques/commentaires/suggestions, que le visiteur rédigera d'autant plus volontiers qu'il disposera du wiki pour cela, évitant ainsi le recours au courrier électronique (qui est plus contraignant). Par la suite, le fait de passer par un wiki lui permettra de contribuer directement à l'enrichissement de son contenu, raison d'être de tout wiki.

Bref, l'idée générale est de procéder par petits apports, afin d'atteindre le point critique pour amorcer la pompe, c'est-à-dire susciter l'intérêt de personnes au point de les pousser à contribuer au projet, ce qui attirera d'autres contributeurs, et ainsi de suite. Cette démarche me semble plus facile et nettement moins coûteuse en temps que de rédiger une documentation exhaustive ! La mise en place d'un forum, et éventuellement d'un weblog (encore que, dans ce contexte, je n'en vois pas trop l'utilité), ainsi que d'un logiciel de suivi de bogues permettront de renforcer cette démarche.

Parmi les logiciels (libres, bien entendu) disponibles (wikis, fora, weblogs, ...), lesquels vous semblent les plus adaptés à l'usage que je compte en faire, sachant que je dispose de mon propre (modeste) serveur (pentium 166 MHz, 80 Mo , 1.2 Go sous Debian Woody) accessible par Internet ? Et surtout, comment dois-je organiser les documents dans le wiki ? Quelles doivent en être les rubriques, question qui se pose également pour le forum ? Existe-t'il des sites, mettant en oeuvre des outils similaires dans un contexte similaire, dont je pourrais m'inspirer ? Dois-je tout rédiger en anglais pour tenter d'attirer le plus de monde possible, ou laisser cela à de futurs éventuels contributeurs ?

Tout autre question/remarque/commentaire/suggestion sur le sujet est évidemment également le/la bienvenu(e).

[pjc]

Pour commencer tu peux utiliser Doxygen pour documenter ton code et générer directement une documentation en ligne en HTML.

Tu peux aussi utiliser ArgoUML pour documenter en UML l'organisation de tes classes.

Ensuite pour la mise en place d'un wiki de documentation je te conseille DokuWiki, vraiment immédiat à mettre en service ; sinon mediaWiki est sûrement le plus complet mais il est plus exigeant pour son installation.

Tu peux aussi jeter un coup d'oeil à Trac qui intègre Wiki, interface Subversion et gestion des bugs ; un bon produit mais le wiki est un peu léger.

Concernant l'organisation des documents, je ne pense pas qu'il soit possible de définir une règle. Un site attractif et didactique sur les premières pages permettra de susciter l'intérêt des visiteurs occasionnels. Les pages plus techniques peuvent apparaître sur un second niveau.

Quant à la langue du site, tout dépend de ta cible. Je pense que pour des bibliothèques, qui s'adressent donc en priorité à des développeurs habitués à lire des documentations en anglais, cette langue te permettra de toucher le plus grand nombre.

Pierre-Jean

[Epeios]

Pour commencer tu peux utiliser Doxygen pour documenter ton code et générer directement une documentation en ligne en HTML.

Ce système nécessite l'écriture de commentaires dans le code. C'est ce que je faisais au début (à l'usage d'un logiciel maison que j'utilisais pour génèrer les 'quickdoc' du site), mais cela s'est révèlé trop contraignant à l'usage. Au final, j'ai cessé de commenter mes sources (nombreux sont ceux encore commentés, mais les commentaires en question sont obsolètes). Je sais que cela va à l'encontre des bons usages en matière de développement, néanmoins, en pratique, l'absence de commentaires ne s'est pas révèlé gênante.

En outre, le genre de documentation génèrée par des logiciels du type Doxygen, bien qu'indispensable à plus ou moins long terme, n'est pas le genre de documentation qui serait utile à un néophyte.

Tu peux aussi utiliser ArgoUML pour documenter en UML l'organisation de tes classes.

Je ne connais pas trop UML (même pas du tout). Peut-être est-ce effectivement utile, mais, pour la même raison que ci-dessus, je ne pense pas qu'à court terme cela soit indispensable. Mais je garde l'idée sous le coude.

Ensuite pour la mise en place d'un wiki de documentation je te conseille DokuWiki, vraiment immédiat à mettre en service ; sinon mediaWiki est sûrement le plus complet mais il est plus exigeant pour son installation.

Le problème, avec DokuWiki, c'est qu'il n'y a pas de système de commentaires ; or, je pense que c'est indispensable pour servir mes desseins. Quand à mediaWiki, c'est trés complet, avec beaucoup de fonctionnalités, trop peut-être eu égard à la puissance de mon serveur. Mais je vais essayer, et s'il tient la charge ...

Tu peux aussi jeter un coup d'oeil à Trac qui intègre Wiki, interface Subversion et gestion des bugs ; un bon produit mais le wiki est un peu léger.

En effet, à l'instar de DokuWiki, le wiki ne gère pas les commentaires ...

Concernant l'organisation des documents, je ne pense pas qu'il soit possible de définir une règle. Un site attractif et didactique sur les premières pages permettra de susciter l'intérêt des visiteurs occasionnels. Les pages plus techniques peuvent apparaître sur un second niveau.

Comme au début il y a aura peu de documents, leur hiérarchisation n'aura que peu d'importance. Mais lorsque leur nombre deviendra conséquent, il est important de les organiser, et j'ignore si les wikis (mediaWiki en particulier) permettent cela facilement. Si c'est le cas, ma question n'est pas primordiale, mais, dans le cas contraire ...

Quant à la langue du site, tout dépend de ta cible. Je pense que pour des bibliothèques, qui s'adressent donc en priorité à des développeurs habitués à lire des documentations en anglais, cette langue te permettra de toucher le plus grand nombre.

Pour le site actuel, j'avais tenu le même raisonnement, d'où le fait qu'il soit rédigé en anglais. Mais c'est trop laborieux, pour un résultat trop approximatif. Je pense que je vais me limiter au français ; je toucherais moins de monde, mais le résultat sera plus complet et de meilleurs qualité, ceci compensant peut-être cela.

Merci pour cette intervention !