Quels outils utilisez-vous pour documenter vos applications Java ?
Sont-ils intégrés au processus de build ?

Le , par Michenux, Membre régulier
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 ?


Vous avez aimé cette actualité ? Alors partagez-la avec vos amis en cliquant sur les boutons ci-dessous :


 Poster une réponse

Avatar de Zenak Zenak - Futur Membre du Club https://www.developpez.com
le 18/01/2010 à 23:13
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.
Avatar de gronono gronono - Membre confirmé https://www.developpez.com
le 19/01/2010 à 0:28
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
Avatar de miaou_ miaou_ - Membre à l'essai https://www.developpez.com
le 19/01/2010 à 8:02
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...
Avatar de jabbounet jabbounet - Membre expert https://www.developpez.com
le 19/01/2010 à 10:03
Citation Envoyé par Zenak  Voir le message
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...
Avatar de thebloodyman thebloodyman - Membre confirmé https://www.developpez.com
le 20/01/2010 à 3:12
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...)
Offres d'emploi IT
Responsable transverse - engagement métiers H/F
Safran - Ile de France - Corbeil-Essonnes (91100)
Architecte électronique de puissance expérimenté H/F
Safran - Ile de France - Villaroche - Réau
Architecte technique des systèmes d'information H/F
Safran - Ile de France - Évry (91090)

Voir plus d'offres Voir la carte des offres IT
Responsables bénévoles de la rubrique Java : Mickael Baron - Robin56 -