Discussion :

[Invité]

L'objectif est de partager sur la manière dont vous gérez votre documentation (guide de référence, developper guide, installation guide, etc...) ?

On peut citer un certain nombre d'outils pour créer des documents comme
- traitement de texte (openoffice/word)
- wiki
- docbook
- xdoc
Lesquels utilisez-vous et dans quel cadre ?

Chacun de ses outils ont leurs avantages/inconvénients :
- Export dans différents formats (pdf,html,...)
- Facilité d'utilisation
- Format non libre de l'écriture de la documentation (xml)
- Gestion de profiles de génération
Quels sont pour vous les critères importants pour sélectionner un de ses outils ?

Enfin, votre outil de documentation s'intègre t-il dans votre outil de build ?
- avec maven ? si oui, quel plugin ?
- avec ant ?

[Zenak]

Pour moi, c'est un bonne javadoc bien complète et un document pdf qui faire le tour du projet java. Il est facile d'écrire des formules et d'utiliser un langage avec LateX.

[gronono]

Pour nous, c'est :

- javadoc dans le code. Elle est généré durant le nightly-build via le plugin maven, et est déployé sur le site du projet.
- documentation technique dans un wiki (confluence)
- la documentation technique peut être (suivant le besoin) enrichie en incluant des diagrammes UML générés par Visual Paradigm. Les diagrammes sont mis à jour lors du nightly-build (via une tâche ant dans maven durant la phase site)
- manuel utilisateur aussi dans confluence (mais dans un espace séparé). Il est écrit par la MOA.
- les specs sont aussi dans Confluence.
- le nightly-build est géré par bamboo

Le wiki est vraiment un plus sur le projet. C'est souple, rapide, efficace. J'ai déjà travaillé avec des documents Word et c'était galère pour l'archivage, la modification concurrentielle, le partage, ...

Voila
Gronono

[miaou_]

Concernant les documents clients (guide d'installation, guide utilisateur, guide d'exploitation...), ceux-ci sont réalisés au format DocBook.

Avantages :
* format libre.
* génération intégrée au build (tache ant).
* sortie au format pdf et/ou javahelp, permettant ainsi d'avoir simultanément la doc papier et la doc en ligne pour un même document.
* possibilité de rédiger les documentations directement dans le flux xml (la xsd n'est pas si compliqué que cela si on se cantonne à qques tags).

Désavantages :
* un bon éditeur gratuit ? (je me suis trop habitué à xmlOxygen, je l'avoue)


Concernant la doc utilisateur, une bonne javadoc générée et publiée toutes les nuits - via hudson - sous notre wiki (Trac), c'est simple et nous convient pour l'instant. De plus, Trac permet de référencer des documents archivés sous svn (ou d'autres logiciel de gestion de versions), donc tout document au format word/visio, supports de présentation ou autres...

[jabbounet]

Pour moi, c'est un bonne javadoc bien complète et un document pdf qui faire le tour du projet java. Il est facile d'écrire des formules et d'utiliser un langage avec LateX.

A peu pres pareil a base de javadoc intégré dans le build plus un document word a coté pour compléter.

le souci c'est que certains developpeurs oublient de documenter ce qu'ils font et qu'il faut toujours relire ce qui a été fait, mais là c'est plus de l'organisation...

[thebloodyman]

Vive les wiki

Je trouve très pratique Confluence pour documenter les aspects techniques au niveau ET fonctionnels d'une appli.
Pour la Javadoc, j'ai de bons résultats pour l'instant sur les Builds de nuit Hudson reposant sur des projets Maven.
Pour les tests d'acceptance (spécifications)et les bugs, JIRA donne d'assez bons moyens (découpage d'un scénario fonctionnel en unité plus fine pour les tâches,commentaires, pièce jointe, affectation des tâches...)