Documentation et projets libres commerciaux : sondage

Posté par  . Modéré par Nÿco.
Étiquettes : aucune
0
5
mai
2004
Doc
L'écriture de documentation n'a jamais été l'activité préférée des développeurs. Comme le montrent les liens annexés, du travail reste à faire. Quelle est votre opinion par rapport à la documentation des logiciels libres ? Pour les projets sur lesquels vous participez, de manière bénévole ou pour votre travail, y a-t-il de la documentation et qui s'en occupe ? les développeurs ? des rédacteurs internes au projet ? un sous-traitant ? Quelle est la licence de la documentation ? Dans le contexte de développements logiciels propriétaires, avec un plan d'affaire traditionnel, le coût d'écriture et de traduction de la documentation peut être intégré au coût global de production et reporté sur le prix du produit. Dans le cadre de logiciels libres, pour lesquels les modèles commerciaux sont encore au stade expérimental, la documentation peut constituer une lourde charge si l'on considère les coûts de production ou un considérable atout si l'on considère la valeur ajoutée par rapport à un logiciel dont la valeur d'acquisition est généralement nulle.

Il serait intéressant de connaître l'expérience personnelle de chacun et la politique adoptée par les SSLL et autres sociétés commerciales qui développent des logiciels libres.

Aller plus loin

  • # Réponse

    Posté par  . Évalué à 6.

    - Mon opinion, pas forcément en rapport avec le libre, est qu'un "logiciel" très bien documenté sera plus utilisé et plus populaire qu'une killerapp mal documentée.
    Et que je dis logiciel, ca peut etre un soft (du point de vue end-user) ou une API (du point de vue développeur). Moi le premier, je préfère avoir un truc plus lent et bien documenté, qu'une merveille nécessitant de découvrir à la main toutes les fonctionalités.
    Dans le domaine scientifique, FEMLAB est une réussite. Et bien ce n'est pas du tout du tout le meilleur code que j'ai vu. Par contre c'est souple, bien concu, bien documenté. Ca aide BEAUCOUP. Tout le monde n'a pas envie de passer ses journées à découvrir des fonctionnalités "cachées".

    - Je travaille sur un projet universitaire basé (quasiment uniquement) sur de la documentation d'algos existant.
    - Dans mon entreprise c'est une priorité officielle la doc, et on arrive quand même des fois à se retrouver avec des libs pas documentés, ou alors avec des version archaiques.

    • [^] # Documentation et succès d'un logiciel

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

      Dans le cas d'un logiciel commerciale libre la documentation est primordiale s'il existe déjà d'autre projets sur le même segment de marché.
      Lorsqu'un utilisateur teste un logiciel avant d'en acheter le service de personnalisation, si la documentation est pauvre ou uniquement commerciale il sera rapidement frustré de ne pas pouvoir reproduire ce qu'il a vu quand on lui a présenté de logiciel. Au bout de deux ou trois jours de galère il dira que le logiciel est sympa, très puissant, mais inutilisable tel que.
      J'ai vu des boîtes perdre des contrats là-dessus, et d'autres en gagner.

      Par contre une mauvaise documentation des API (ou une documentation générée automatiquement), sans tutorial digne de ce nom, sans manuel pour le dévellopeur et l'administrateur ne donnera aucun engouement dans le projet pour les dévellopeurs éventuels. Donc une communauté quasiment nulle. Les documentations en retard de trois versions, ou uniquement dans la langue de Molière ou de Shakespeare ne sont pas pour aider non plus.

    • [^] # Re: Réponse

      Posté par  . Évalué à 4.

      Ca peut etre un soft (du point de vue end-user) ou une API (du point de vue développeur)

      C'est tout à fait vrai pour une API, mais ça l'est à mon avis beaucoup moins pour une application pour laquelle la plupart des utilisateurs ne liront jamais la doc et se contenteront d'utiliser les fonctionnalités qu'ils ont comprises intuitivement... et le problème en général avec la doc des applications, c'est que sont documentées que les fonctionnalités que l'on peut comprendre tout seul, c'est-à-dire, par exemple, qu'on va avoir un bon gros paragraphe sur le menu "edit" pour nous dire que "copier" correspond à "placer le texte sélectionné de la fenètre d'édition dans le presse papier", mais dans le menu "tool", l'entrée "conversion" sera documenté comme "effectue la conversion" sans savoir quelle source, quelle destination, quels formats etc... Le pire des exemples de ce genre est l'aide de windows dont le texte est complétement redondant par rapport à l'interface...

      Sinon, dans un aute domaine,, aucun des 3 liens ne parlent des différentes licences utilisables pour une doc... quelqu'un a plus d'infos dessus, ou une doc?

  • # Quelle est votre opinion par rapport à la documentation des logiciels libres ?

    Posté par  . Évalué à 5.

    Quelle est votre opinion par rapport à la documentation des logiciels libres?
    J'ai souvent entendu des développeurs dire qu'il faut que ça soit des utilisateurs qui écrivent la doc...

    • d'un côté ça arrange bien les développeurs, car ils n'aiment pas ça

    • de l'autre ça permet d'éviter tout un jargon technique que le développeurs seraient tenté d'utiliser dans la doc, la rendant difficile à lire, et pas là-même, inutilisable...

  • # Perso

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

    Je trouve qu'il manque souvent de la documentation en français. J'ai par exemple essayé bastille il y'a peu, c'est très simple à mettre en place en mode interactif, mais c'est en anglais. Même quand on comprends l'anglais, c'est toujours beaucoup plus agréable de configurer un logiciel ou lire la doc dans sa langue natale. C'est pourquoi je me suis lancé sur une traduc libre de la doc d'icecast2, par exemple.
    Avoir des fichiers de conf avec des commentaires localisés serait un gros plus également.

    Quelqu'un pour traduire le HOWTO: write bad documentation that looks good ? :)

Suivre le flux des commentaires

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