Calenco : une solution pour la documentation des projets libres ?

Posté par  . Modéré par tuiu pol.
Étiquettes :
12
3
mai
2010
Doc
Les développeurs n'aiment pas écrire de la doc', c'est bien connu. Les logiciels libres sont souvent issus de projets de développeurs. Et une des conséquences est que peu de logiciels libres proposent une documentation vraiment professionnelle.

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

  • # Documentation de quoi?

    Posté par  . Évalué à 7.

    Comme ça fait un petit temps que je n'ai pas vu de commentaire aigri et que je n'aimerai pas perturber les statistiques de NoNo<, je vais poster un commentaire aigri.

    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  . Évalué à 7.

      Réponse blasée vaguement condescendante (mais j'ai la flemme de tout ré-écrire mieux, mes excuses par avance) à un commentaire aigri :
      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  (site web personnel) . Évalué à 6.

    Le sujet m'intéresse, étant confronté au problème avec les logiciels que je développe, mais il me semble que le vrai problème c'est qui écrit la doc, et comment. La question de savoir dans quel format est une bête question technique que la plupart des développeurs savent déja régler: on peut écrire en docbook, html, tex, wiki, et convertir dans tous les sens: ce n'est pas toujours parfait et on peut y perdre du temps, mais ça me parait pas crucial.

    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  (site web personnel) . Évalué à 3.

      Quelle est votre expérience?

      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  (site web personnel) . Évalué à 2.

      Je suis tombé récemment sur un moteur de wiki qui utilise un dépôt versionné genre Subversion pour stocker les pages. Ça devrait pouvoir vous servir, en cherchant un peu vous devriez retrouver son nom…
      • [^] # Re: Facteurs humains

        Posté par  (site web personnel) . Évalué à 2.

        http://ikiwiki.info/

        ?

        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
  • # Doxygen pour documenter le code

    Posté par  . Évalué à 2.

    En ce qui concerne la documentation du code, je rappelle l'existence de Doxygen ([http://www.stack.nl/~dimitri/doxygen/]), qui fait pour d'autres langages ce que fait la Javadoc (par exemple [http://java.sun.com/j2se/javadoc/writingdoccomments/index.ht(...)]) en standard. On peut déjà documenter beaucoup de choses directement dans le code.

    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  . Évalué à 4.

      Il me semble que ça ne réponds pas au même besoin. Les outils cités permettent essentiellement de documenter une API via des commentaires dans le code. Il s'agit d'une documentation destinée exclusivement aux développeurs. Il y a d'autres niveau de documentation : Documents de design général et d'architecture qui permettent de comprendre la logique générale avant de plonger dans le code, et surtout la doc destinée à des non-developpeurs : Manuel d'utilisation, tutoriel, etc. C'est plutôt ce genre de doc que vise le projet présenté. C'est relativement proche d'un wiki avec avec export dans divers formats.
      • [^] # Re: Doxygen pour documenter le code

        Posté par  (site web personnel, Mastodon) . Évalué à 3.

        bah, on crie qu'il n'y a pas de documentation sans préciser à qui doit s'adresser ladite documentation... pour documenter l'API (à l'intention des développeurs), effectivement il vaut mieux que la documentation soit faite en même temps que le code (perldoc, javadoc, rdoc, et plus largement doxygen, noweb, etc.) dire donc que ça ne répond pas au besoin, je ne suis pas d'accord car il n'est dit nulle part que ce n'est pas le besoin :p

        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  . Évalué à 6.

    S'ils documentaient avant de coder, ça permettrait probablement d'avoir une doc à jour, et de s'assurer que le code fait exactement ce qui est documenté ?
    • [^] # Re: Peut-être que les développeurs bossent à l'envers ?

      Posté par  (site web personnel) . Évalué à 4.

      Oui, après tout certains considèrent que les tests unitaires sont de la documentation, et certains disent qu'il faut absolument faire les tests avant de faire le code.

      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  . Évalué à 2.

        C'est clair qu'avoir seulement quelques commentaires dans le code n'aide pas à attirer de nouveaux développeurs. Même s'il y a beaucoup de commentaires, il n'est parfois pas facile de comprendre la structure générale du code, et on ne sait pas vraiment par où commencer la lecture (le main() est toutefois un bon point de départ, généralement).

        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  . Évalué à 4.

    Je suis assez étonné par les quelques réactions que je peux lire.

    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  . Évalué à 2.

      Il y a effectivement du boulot concernant la doc utilisateur. C'est souvent du au fait que beaucoup de développeurs bénévoles développent avant tout pour eux même et que leur code n'a pas forcément vocation à être utilisé, ou en tout cas pas par un grand nombre de personnes (et pas Mme Michu).

      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  . Évalué à 2.

      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

      Vraiment? Je trouve pourtant beaucoup plus facilement de l'aide sur les logiciels libres.
      • [^] # Re: De l'importance de la documentation...

        Posté par  . Évalué à 2.

        il y a une différence entre avoir de l'aide (sur un forum, irc, etc.) et avoir de la documentation.

        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  . Évalué à 1.

          Bref, il faudrait des équivalents aux différents truc-code pour l'écriture de la documentation

          ç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  . Évalué à 3.

            je me suis mal exprimé, par truc-code je pensais à l'équivalent des summer google code et autres trucs financés pour écrire des LL mais pour écrire de la documentation

            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  . Évalué à 3.

          il y a une différence entre avoir de l'aide (sur un forum, irc, etc.) et avoir de la documentation.

          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  . Évalué à 1.

      C'est surtout au niveau de l'ergonomie que ca pêche. Avec une bonne ergonomie, le besoin d'une bonne doc devient moins pressant.

      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  . Évalué à 4.

        La doc c'est également l'aide disponible dans le logiciel lui même, quand on clique sur le menu aide et qu'on a un mode d'emploi, c'est également l'aide par bulle quand on passe sur une case à cocher / à remplir qu'on a la bulle d'aide pour expliciter ce que le logiciel attend ou propose de faire
      • [^] # Re: De l'importance de la documentation...

        Posté par  . Évalué à 4.

        Avec une bonne ergonomie, le besoin d'une bonne doc devient moins pressant.

        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  . Évalué à 2.

          Le clavier bepo est conçu pour être ergonomique (minimiser l'effort) mais il n'est pas intuitif (il demande un temps d'adaptation).

          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  . Évalué à 5.

          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.

          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  . Évalué à 5.

    Calenco a l'air intéressant dans la mesure où il parle de document autrement qu'en terme bureautique.
    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.

Suivre le flux des commentaires

Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.