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?
# Facteurs humains
Posté par dbaelde . En réponse à la dépêche Calenco : une solution pour la documentation des projets libres ?. É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?