Ceci a d'ailleurs été à plusieurs reprises cité comme un frein à son adoption en entreprise. Par exemple dans "Fundamental issues with open source software development" by Michelle Levesque: "Without adequate documentation, Open Source projects are inherently at a disadvantage".
Soit en français, dans "Les soucis fondamentaux avec les développements open-source" de Michelle Levesque : "sans documentation appropriée, les projets open-source sont par nature désavantagés".
Développé par l'ancienne équipe documentation de Mandriva, Calenco est un outil Web sous licence AGPL qui peut aider à résoudre ce problème. La version 2.0.1 sortie tout récemment permet d'écrire de la documentation très rapidement avec un rendu pro dans de nombreux formats. Basé sur le format XML DocBook, bien connu de ceux qui connaissent le "Linux Documentation Project", Calenco centralise les contributions de chacun, textes et images, et permet de les assembler pour générer ensuite, du PDF, HTML, RTF, etc.
Dans l'idée de contribuer à l'amélioration de la documentation des logiciels libres, Calenco est proposé gratuitement en SaaS pour tous les projets libres [http://trac.calenco.com/wiki/CalencoForFloss].
Merci à l'équipe de NeoDoc [http://www.neodoc.fr] pour ce projet !
Aller plus loin
- Fundamental issues with open source software development (16 clics)
- Site officiel de Calenco (401 clics)
- Site de développement (104 clics)
- Télécharger sur sourceforge (151 clics)
- Tester (281 clics)
# Documentation de quoi?
Posté par claudex . Évalué à 7.
La dépêche ne dit pas (et le site du projet non plus) de quelle sorte de documentation on parle. C'est de la documentation pour le développeur, pour l'utilisateur, pour les deux? (et quand le développeur est utilisateur, que se passe-t'il? :-))
« Rappelez-vous toujours que si la Gestapo avait les moyens de vous faire parler, les politiciens ont, eux, les moyens de vous faire taire. » Coluche
[^] # Re: Documentation de quoi?
Posté par monde_de_merde . Évalué à 7.
Dans la mesure où il est question de logiciel libre en général je comprends ça comme des logiciel potentiellement destiné pour les développeurs, les utilisateurs, les utilisateurs développeurs et les développeurs utilisateurs. Oui donc tout le monde. Et a priori, mais l'un ou l'autre développeur élitiste me détrompera sans doute, une documentation c'est son contenu qui l'adresse à une certaine catégorie de personnes. C'est pourquoi je pense que Calimachin peut aider à écrire une documentation, au sens général du terme, charge au "documentateur" (?) d'adapter son contenu à sa cible.
Par contre c'est basé sur xml ce machin dirait-on, est-ce vraiment une bonne idée :( ?
# Facteurs humains
Posté par dbaelde (site web personnel) . Évalué à 6.
Par contre, ce qui est dur, c'est de pousser les développeurs à documenter leur production: quand il y a une nouvelle feature ou une modification, il faut le répercuter sur la doc; de temps en temps il pondre ou mettre à jour des tutoriels. Quelles sont vos expériences?
Dans un petit projet (bedwyr) ça marche pas mal d'écrire une doc entre développeurs. Dans mon cas, c'était un PDF généré à partir de tex, écrit une fois pour toutes car le projet ne bouge plus trop.
J'ai plus de mal avec un gros projet (liquidsoap). On a d'abord essayé le wiki pour faire participer les utilisateurs, avec la crainte d'avoir des pages mal finies et une vue d'ensemble hétéroclite... mais de toute façon il n'y a que les devs qui contribuaient. De temps en temps on me disait que la doc était trop austère, qu'il fallait plus de tutoriels intuitifs. A un moment, on en a eu marre d'administrer le wiki (spam notamment, mais aussi maj) et on s'est aussi dit que ce serait bien d'archiver voire versionner autrement qu'avec l'export PDF. Donc on a carrément mis dans notre SVN les fichiers source wiki, avec notre petite moulinette d'export HTML et PDF. Du coup, ça rend plus difficiles les contributions externes. Et par ailleurs les devs sont pas très actifs sur la doc non plus... A côté de ça on a une mailing liste sur laquelle certains problèmes passent souvent, et on a toujours pas été foutus de créer une FAQ dans la doc ou à côté. (Pour info la communauté est relativement petite, un noyau dur d'une dizaine de personnes, et des électrons libres de passage).
Quelle est votre expérience? qui écrit de la bonne doc, développeurs? utilisateurs? en mode wiki ouvert ou juste par certains contributeurs sélectionnés? des idées sur le lien entre le support (mailing liste, irc..) et la doc?
[^] # Re: Facteurs humains
Posté par Zenitram (site web personnel) . Évalué à 3.
Personnellement, je suis à la même conclusion que toi : le problème de traitement des données d'un projet (mise en forme etc...), c'est utile (et donc la dépêche est utile) pour les projets qui ont déjà des gens pour faire la doc.
Car les utilisateurs, ben... Ils sont bien gentils, mais ils... utilisent principalement. Ceux "motivés" pour écrire n'ont pas les compétences.
Pour les projets open source en général, qui n'ont pas de financement pour permettre de payer les gens et donc leur dire "sans doc, pas de paye", pas foule est motivé pour faire ce travail "ingrat", les développeurs bénévoles préfèrent faire ce qui leur plait ce que je comprend). Ce sera seulement après avoir trouvé un bon financement qu'on peut passer à l'étape de recherche du bon logiciel de gestion de doc... Personnellement, je regarderai ce logiciel qu'en j'en serai la (c'est pas près d'arriver :) )
Je prend comme référence la doc Qt : derrière, il y a des mecs payés pour faire la doc, et elle est faite, très bien faite, assez détaillée (il y a encore quelques manques sur certaines méthodes, mais globalement bonne).
[^] # Re: Facteurs humains
Posté par 🚲 Tanguy Ortolo (site web personnel) . Évalué à 2.
[^] # Re: Facteurs humains
Posté par Matthieu Moy (site web personnel) . Évalué à 2.
?
Jamais essayé, mais le principe me plait beaucoup. Il dissocie assez bien :
* L'édition de page
* Le rendu (possible avec pleins de moteurs différents, genre ReST, Mediawiki, ...)
* Le versionning, totalement délégué à un gestionnaire de versions.
Du coup, on peut éditer des pages en ligne, mais aussi par exemple :
git clone ...
$EDITOR les-pages-que-je-veux
git commit
git push
[^] # Re: Facteurs humains
Posté par Édouard Siha . Évalué à 7.
Je salue la classe et l'élégance avec laquelle tu as évité un (n+1)ème troll sur vim/emacs. Chapeau !
[^] # Re: Facteurs humains
Posté par Alexandre COLLIGNON (site web personnel) . Évalué à 5.
Alexandre COLLIGNON
[^] # Re: Facteurs humains
Posté par 🚲 Tanguy Ortolo (site web personnel) . Évalué à 4.
# Doxygen pour documenter le code
Posté par Olivier Jeannet . Évalué à 2.
De plus, Doxygen permet de créer de la documentation HTML depuis un ensemble de fichiers sources, avec des liens entre fichiers sur les fonctions et les variables ; c'est assez puissant pour prendre en main un code à maintenir et naviguer dedans, je l'ai utilisé sur du C par exemple.
[^] # Re: Doxygen pour documenter le code
Posté par Croconux . Évalué à 4.
[^] # Re: Doxygen pour documenter le code
Posté par Gil Cot ✔ (site web personnel, Mastodon) . Évalué à 3.
pour documenter le design général et l'architecture, je pense que les bases peuvent se faire à travers un wiki à condition de prendre le temps de le faire (mettre les idées au clair) avant de commencer a coder...
pour la documentation utilisateur, tout dépend du niveau de documentation voulu... pour un manuel rapide, ça peut être mis en place aussi par un wiki et être nourri par les développeurs et les testeurs... les manuels détaillés et les tutoriels sont par contre un boulot de rédaction à part entière pour lequel hélas peu de développeurs sont rompus
“It is seldom that liberty of any kind is lost all at once.” ― David Hume
# Peut-être que les développeurs bossent à l'envers ?
Posté par totof2000 . Évalué à 6.
[^] # Re: Peut-être que les développeurs bossent à l'envers ?
Posté par mgoeminne (site web personnel) . Évalué à 4.
Il me semble donc intéressant d'envisager d'écrire la documentation avant d'écrire le code... C'est d'ailleurs un peu ce qu'on a fait pour Eiffel : définir la spécification complète du langage avant de l'implémenter... Et si le résultat n'est pas très populaire, je pense qu'on peut objectivement dire qu'il est d'une bonne qualité.
Dans le cadre de ma thèse, je suis amené à m'intéresser aux "entités" tournant autour des logiciels (libres, surtout), et à leur co-évolution. J'ai remarqué que ces derniers temps on avait tendance à parler de la documentation comme d'un pilier du logiciel (au même titre que le code source ou les rapports d'erreurs, par exemple), mais qu'elle était généralement négligée et surtout pas sérieusement prise en compte par les outils actuels.
Alors oui, maintenant on peut lancer un wiki/un site web/un planet en rapport avec le logiciel, mais toutes ces informations restent faiblement organisées et intégrées : on ne peut pas clairement et systématiquement associer une documentation avec une fonctionnalité, par exemple. Ce n'est sans doute pas trop grave pour l'utilisateur final, mais dans le cas des logiciels libres, il doit être possible (et normalement c'est espéré) que de nouvelles personnes viennent se joindre à l'équipe de développeurs, que d'autres s'en aillent, ...Bref qu'il y ait un roulement qui oblige une transmission aussi efficace que possible de la "présentation" du projet.
Ce qui serait super, ce serait que les forges intègrent ce genre de chose. La gestion des versions de la doc y serait certes nécessaire, mais de mon point de vue pas tant pour éviter le vandalisme que pour pouvoir marquer une co-évolution entre la documentation et le reste du projet. Imaginez qu'on puisse sans se prendre la tête découvrir en une heure l'évolution du projet et son état actuel, qu'on puisse voir de manière synthétique quels sont les éléments du projet, et à quoi ils servent... Cela faciliterait certainement la vie des nouveaux (et des pas nouveaux aussi, d'ailleurs) développeurs, et l'utilisateur pourrait avoir une documentation à jour, ou à défaut il pourrait déterminer là où elle pêche.
Peut-être que placer l'écriture de la documentation à côté de l'écriture du code source ou de la traduction valoriserait mieux celle-ci, et inciterait davantage de personnes à y participer.
[^] # Re: Peut-être que les développeurs bossent à l'envers ?
Posté par swilmet . Évalué à 2.
Mais écrire d'abord la documentation (pour développeurs) avant le code, ça me parait une perte de temps si on s'aperçoit en codant qu'on n'a pas prévu tous les cas possibles et où une réécriture en profondeur de la documentation est nécessaire...
Pour ce qui est de la documentation pour utilisateurs, autant le faire après le code pour pouvoir insérer des captures d'écran, faire référence à telle ou telle option bien spécifique dans les préférences, etc.
# De l'importance de la documentation...
Posté par goom . Évalué à 4.
Il me semble que si techniquement le LL n'a généralement rien a envier aux logiciels propriétaires, au niveau documentation (et ergonomie, mais là n'est pas la question) il y a des efforts à faire, j'entends par documentation celle qui est utile à l'utilisateur final, pas la documentation du code source pour en comprendre les arcanes.
Il me parait évident que les développeurs n'ont pas tous vocation à créer de la documentation et inversement, ceux qui écrivent de la documentation ne sont pas nécessairement les développeurs. Tout le monde n'a pas envie d'aller chercher sur Internet des trucs et des astuces, de la documentation pour utiliser son logiciel, surtout s'il est destiné à un public non informaticien.
Pour cela, encore faut-il désacraliser le code et accepter que la conquête du public se fait avec d'autres arguments que la simple ouverture du code. Cette réflexion englobe également l'ergonomie, le look des applications (cf la discussion sur les scanners et notamment le logiciel vuescan dont le look et l'intuitivité surpasse l'offre en matière de numérisation qu'on peut trouver dans le monde du LL alors que je suis convaincu qu'il y a largement de quoi avoir un équivalent libre)
[^] # Re: De l'importance de la documentation...
Posté par Croconux . Évalué à 2.
Sur un projet qui fait beaucoup d'audience ou pour lequel on est tenu (commercialement) de faire du support, documenter est une évidence. Quand on en a marre de se prendre pour la 10e fois un bug qui n'en est pas un sur une fonctionnalité mal comprise, on met à jour la doc ou on ajoute une entrée dans la FAQ, ne serait-ce que pour se faciliter la vie et limiter le flux entrant. Dans la monde du libre, on est moins impacté. Les utilisateurs ont tendance à tester un logiciel et abandonner pour passer à autre chose s'ils rencontrent un problème. Ils sont peu nombreux à remonter des bugs. Du coup le développeur ne se rends pas compte qu'il y a un réel problème et comme il n'a pas de soucis, il ne change rien.
[^] # Re: De l'importance de la documentation...
Posté par alice . Évalué à 2.
Vraiment? Je trouve pourtant beaucoup plus facilement de l'aide sur les logiciels libres.
[^] # Re: De l'importance de la documentation...
Posté par goom . Évalué à 2.
A la limite une bonne documentation se suffit à elle-même, la recherche d'aide est tributaire d'un autre intervenant (et il faut connaître les canaux pour demander de l'aide ;-) )
Bref, il faudrait des équivalents aux différents truc-code pour l'écriture de la documentation
[^] # Re: De l'importance de la documentation...
Posté par gde . Évalué à 1.
ça c'est pas ce qui manque, y'a latex, pod, groff (pour les plus furieux) et d'autre que je ne dois pas connaitre.
Le truc c'est que ça demande de vrai compétence particulière pour écrire de la doc : de la pédagogie, une bonne orthographe et un peu de connaissance en typographie pour ne nommer que ça. Et faut bien le dire, ça peut faire un métier à lui tout seul. Donc bon, demander à un dev de faire tout type de documentation on peut comprendre que ça peut en crisper quelques-uns.
[^] # Re: De l'importance de la documentation...
Posté par goom . Évalué à 3.
Un point qui me vient également, il ne faut pas penser la documentation qu'en terme de choses complexes à expliciter. Tout ce qui peut paraître trivial mérite quand même de la documentation pour les utilisateurs. Il y a des utilisateurs qui ne savent pas ce qu'est un menu contextuel par exemple, d'autres ne savent pas que Dolphin, gestionnaire de fichiers de KDE, peut ouvrir plusieurs onglets et diviser sa fenêtre, ripper ses CD par un simple copier coller avec Dolphin, etc. Tout ça c'est basique ... quand on sait faire
[^] # Re: De l'importance de la documentation...
Posté par alice . Évalué à 3.
J'inclu la documentation dans l'aide. Dans le monde libre, il y a beaucoup de manpage, de tutoriaux et d'articles. Bien sûr ça dépend beaucoup des projets, mais en général je suis plus souvent à poil avec les logiciels propriétaires qu'avec les logiciels libres.
[^] # Re: De l'importance de la documentation...
Posté par grid . Évalué à 1.
Parce que 80% des utilisateurs n'ouvrent pas une doc.
Je sais, dans un monde de bisounours, les gentils utilisateurs iraient jeter un coup d'oeil sur la doc avant d'utiliser un logiciel.
[^] # Re: De l'importance de la documentation...
Posté par goom . Évalué à 4.
[^] # Re: De l'importance de la documentation...
Posté par Croconux . Évalué à 4.
L'ergonomie et l'intuitivité ne sont pas la même chose. Pour prendre un exemple qui touche certains ici : Le clavier bepo est conçu pour être ergonomique (minimiser l'effort) mais il n'est pas intuitif (il demande un temps d'adaptation). Pour l'interface d'un logiciel, c'est pareil. Certains logiciels permettent de rapidement trouver ses marques mais réclament un grand nombre d'opérations (menu, boite de dialogue, etc). A l'inverse d'autres sont plus austères au début mais très efficaces une fois qu'on a les a en main.
L'ergonomie est relative. Tout dépend du public auquel on s'adresse, des codes/habitudes du métier/domaine. Un logiciel de compta par exemple peut très bien sembler imbitable pour le quidam moyen mais complètement logique pour la personne dont c'est le métier parce qu'il présente les informations comme les comptables on l'habitude de les écrire. Si on conçoit ce genre de logiciel en fonction des critères d'un individu lambda (non comptable), le comptable va être paumé.
Tout ça pour dire qu'un logiciel, même ergonomique et intuitif , à besoin d'une doc, éventuellement intégrée au logiciel ou l'on peut rechercher comment faire telle au telle action.
Parce que 80% des utilisateurs n'ouvrent pas une doc.
Peu de gens lisent la doc _avant_ d'utiliser un logiciel mais lorsqu'ils rencontrent une difficulté et ne trouvent pas comment faire quelque chose il se tournent vers la doc. Un peu comme quand on achète un nouvel appareil. La plupart des gens commencent par le brancher et trifouiller les boutons puis ouvrent finalement le bouquin quand ils se rendent compte qu'il n'arrivent pas à régler l'heure dessus.
[^] # Re: De l'importance de la documentation...
Posté par ZeroHeure (site web personnel) . Évalué à 2.
Je suis en train de l'apprendre et le trouve au contraire assez intuitif: après 2-3 séances, certaines touches, certaines combinaisons de touche plutôt, viennent naturellement sous les doigts. Par contre il me faut réfléchir pour indiquer où se trouvent ces touches. L'acquisition des automatismes va donc plus vite que la mémorisation des touches.
De même on s'habitue rapidement à la frappe alternant main gauche et main droite (ou mieux dit: doigt gauche et doigt droit), il n'y a pas de réflexion nécessaire pour savoir "sous quelle main" la touche est placée.
si ça n'est pas intuitif...
"La liberté est à l'homme ce que les ailes sont à l'oiseau" Jean-Pierre Rosnay
[^] # Re: De l'importance de la documentation...
Posté par ZeroHeure (site web personnel) . Évalué à 5.
Toi tu n'es pas administrateur système...
Quand ils rencontrent une difficulté ils disent que ça ne marche pas et que le logiciel truc est mieux. En 15 ans de métiers, je n'ai vu qu'un seul utilisateur "normal" lire une doc. Après que j'ai beaucoup insisté.
"La liberté est à l'homme ce que les ailes sont à l'oiseau" Jean-Pierre Rosnay
# La doc est un élément de configuration
Posté par 6Ber Yeti . Évalué à 5.
Reste qu'il semble oublier un élément essentielle. Une doc, comme un fichier source est / doit être un élément de configuration. Un "truc" (les qualiticiens disent artefact pour faire savant) que l'on doit retrouver dans la livraison et qui doit être en cohérence avec les autres produits (mieux que trucs, non ?) de développement.
A ce titre, il me semble qu'un élément essentiel est l'intégration avec un outil de gestion de configuration / gestion des changement, voire quelque chose de plus ambitieux comme Redmine ou mieux encore une Forge logicielle. Mais quoi qu'il en soit, le point de départ, c'est le client.
Autrement dit, au centre est le système de gestion des changements (c-a-d au départ les besoins des utilisateurs) autour duquel soit s'articuler tout le reste. A commencer par la documentation.
Donc, le système de gestion documentaire doit s'arrêter là où commence la gestion des changements / configuration. Qu'il intègre un workflow, soit. Mais surtout pas une gestion interne des versions. Ou bien cela doit n'être qu'une interface avec le système de gestion de configuration.
Sinon, ça réinvente la roue, ça introduit de la confusion, et ça isole la doc du produit. Ce qui n'est pas souhaitable.
[^] # Re: La doc est un élément de configuration
Posté par ZeroHeure (site web personnel) . Évalué à 2.
"La liberté est à l'homme ce que les ailes sont à l'oiseau" Jean-Pierre Rosnay
Suivre le flux des commentaires
Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.