Documentation Quel langage utiliser? - Page 1

Pour mon taff cet été je dois écrire de la documentation (des mini howto sur 1-2 fonctions de logiciels) sous formes de petites fiches (maxi 2 pages) à destination des employés.

Donc moi ni une ni deux je me met en mode geek et je commence à me faire un petit template sympatoche en LaTeX. Sauf que là mon supérieur (qui ne connaissait pas LaTeX) déplore que le format de sortie (PDF) ne soit pas réexploitable.
Donc en fait il va falloir que je rédige la doc de façon à ce que ça soit réutilisable. La boite ayant 99,99% de ces postes sous Win Word (ou OpenOffice) semble donc le coix désigné, mais j'aimerai éviter si possible d'utiliser un traitement de texte WYSWYG.

Ma question est donc vers quel langage puis-je me tourner pour écrire de la doc "propre" tout en sachant qu'il faudra que ça soit réexploitable (rééditable) par derrière?

J'ai entendu parler ça et là de DocBook. C'est bien? Y-at'il des IDE pour ça (pour latex j'utilise un plugin de gedit qui me donne des boutons pur compiler et afficher en un clic c'est nikel)? Avez-vous deja testé?

Donc voila j'attends vos conseils et avis de geek avisés now

PS: J'ai vraiment hésité à poster ici, donc si ce topic est vraiment HS ne vous gênez pas pour le déplacer (pardon alors pour lé darngement occasionné).

html?

ben oui c'est con mais c'est ultra simple au moins.

sinon openoffice (ou word)

et je pense que tu te mélanges sur "wysiwyg". ou alors c'est moi.

Mais il a fumé quoi, ton supérieur? Évidemment que le format de sortie n'est pas exploitable, c'est le format d'entrée qu'il faut éditer!

Rah, il est vraiment con de pas payer une formation LaTeX d'une semaine à tous les gens de la boite suceptibles de toucher ton doc!

tu réfléchis Kevin des fois?

Question bête : pourquoi ne pas utiliser Word ? (y a des équivalents des templates)

oui, pour la doc d'entreprise c'est le mieux je pense. (tu m'ignores flanker? )

J'ai demandé pourquoi il n'a pas utilisé Word, toi tu as proposé Word

mouahahaha ok

Un framework de doc qui est apriori sympa, et qu'on utilisait au boulot, c'est http://dita.xml.org/

Je peut tenter de sortir ce qu'on avait fait (et il avait été utilisé pour passer de FrameMaker vers ça, donc c'est quand meme assez puissant ^^)

En effet j'ai fait une erreur en parlant de wyswyg au lieu de wysiwyg.

Sinon je suis dans le département info (et oui mon supérieur ne connais pas LaTeX ^^) et donc ya un coté frime a ne pas négliger (si mes journées de 7h étaient remplies je me casserait pas la tête mais là jai largement le temps de frimer (et puis d'apprendre aussi ^^)).

Donc voila un petit truc à base d'XML ça me botte bien. Pour l'HTML ça me plait moyen car c'est pas hyper frime et puis surtout j'apprendrai rien (quoique je suis un gros boulet sur la syntaxe des fois )

Je connaissais pas le DITA, c'est marrant c'est supporté par OASIS comme le DocBook, je vais regarder dans cette voie aussi.

Sinon je viens de voir qu'il existe un plugin eclipse pour DocBook donc je vais l'installer? Quelqu'un l'a essayé? Vous avez des retours d'expérience?

Merci en tout cas de vos réponses

Mais si le PDF c'est réexploitable : http://extensions.services.openoffice.org/project/pdfimport

PpHd: Comme le dit l'article ça reste très limité au niveau des changements qu'on peut apporter par derrière... Mais merci quand même!

personne ne connait latex dans les entreprises. C'est quasiment réservé au monde universitaire qui doit écrire des équations dans les textes.

Le problème, c'est qu'il (le supérieur de JoNas) n'a pas l'air de comprendre ce qu'est un format d'entrée et ce qu'est un format de sortie, ce qui est quand-même grave... Même si on ne connaît pas L^AT_EX en particulier, le fait que le format de sortie n'est pas le format idéal pour éditer devrait rester évident et ne devrait pas constituer un problème.

Si, il a raison, PDF est inmodifiable pour des gens NORMAUX

donc il vaut mieux WORD / OO qui est A LA FOIS un format d'entrée et de sortie, parce que c'est plus RAPIDE

je te souhaite honnêtement et en toute amitié de ne jamais travailler dans une entreprise.

squalyl (./16) :
Si, il a raison, PDF est inmodifiable pour des gens NORMAUX

Mais il ne faut pas modifier le PDF, mais la source L^AT_EX!!!

oui, ok ^^

juste le document word/oo.o, tu vois tout de suite le résultat

bon j'ai pas envie de troller latex/word de bon matin

mais kevin a tout a fait raison, on ne devrait pas avoir les droits de modifications sur un document released, du moins sur son format de sortie. Par contre utiliser latex en entreprise, c'Est a se rouler par terre

Bah moi j'ai bossé dans une entreprise de finance (1,5 milliards sous gestion, 10 millions de chiffres d'affaire), et on faisait du latex. Alors vous pouvez revoir vos préjugés, merci.

Pour le problème du topic, je dirais que c'est assez difficile. Ça dépend de ce que ton supérieur considère comme utilisable : si tu arrives à les convaincre qu'éditer un fichier Latex ou XML c'est pas si difficile que ça, t'as la solution. Sinon il y a LyX, qui a un GUI multi plateformes, mais qui est rapidement limité si on veut faire des trucs un peu funky. Enfin tu peux essayer de faire un source XML et une feuille de style XSLT pour passer ça en format OpenDocument (donc lisible par OpenOffice), mais ça a l'air assez complexe.

je garde mes préjugés tant que je connaitrai pas le % global d'entreprises qui utilisent latex pour leurs documents de travail (pas publications de recherche^^).

On utilisait latex (et parfois LyX) pour notre documentation interne, pas pour des publications de recherche. Et c'était même pas pour écrire plein de symboles mathématiques compliqués, juste pour documenter nos programmes (ça ne remplaçait pas les commentaires doxygen, bien sûr).

certes.

nb d'entreprises qui utilisent latex pour leur doc interne = 1;

= 100% des entreprises dans lesquelles j'ai travaillé

Bref ça veut rien dire d'essayer de faire un recensement. Par contre c'est débile de dire que latex est inutilisable en entreprise. Comme tout le reste, ça dépend du contexte, de l'existant, et il faut savoir s'adapter et ne pas adopter d'attitude sectaire.

Bon après avoir jetté un coup d'oeil à apache forrest qui ne m'a pas tant plu que ça j'ai jetté mon dévolu sur DocBook. C'est bon j'ai compris le prinicpe c'est vraiment puissant et ça demande pas une si grosse masse d'outils par rapport au LaTeX qui necessiterai en plus une formation des gens de la boite.

Je veux dire par là que le service info possèdant deja sur chaque poste un editeur XML (friendly on va dire) et un JRE (+JDK même si pas utile dans notre cas) il ne me reste plus qu'à leur filer un ToolChain du style DocMan pour qu'ils puissent faire mumuse avec. Demain j'essairai avec Vex le plugin DocBook pour Eclipse (existe en standalone aussi) afin de voir si ça marche bien aussi (car avec DocMan ça marche nikel même si c'est un peu long).

Voilà, tout ça pour générer des PDFs voir de l'(X)HTML. Je dois dire que je suis content de découvrir et d'apprendre ça, c'est vraiment très puissant.

./10 pour le format frime, tu fais un format de manpage ou perldoc

Docbook exporte en manpage, par contre je sais pas s'il exporte vers perldoc (mais oui à mon avis si c'est juste un feuille XSL a créer)

damnvoid (./24) :
= 100% des entreprises dans lesquelles j'ai travaillé

Bref ça veut rien dire d'essayer de faire un recensement. Par contre c'est débile de dire que latex est inutilisable en entreprise. Comme tout le reste, ça dépend du contexte, de l'existant, et il faut savoir s'adapter et ne pas adopter d'attitude sectaire.

Dans ma nouvelle boite (une grosse banque US), tous les modèles sont documentés en Latex.

./23 > nb d'entreprises qui utilisent latex pour leur doc interne = 2/2;

Révise tes fractions, 2/2 est ce qu'il a dit.

Bon je déterre un peu mais c'est au cas ou quelqu'un tomberait par hasard sur le topic.

Je suis tombé sur un starter-kit super simple pour Docbook qui mérite le détour! Il est trouvable ici.

Pour ceux qui sont sous GNU/Linux pour écrire le XML il existe le très agréable XML Conglomerate qui comporte des templates Docbook (que demande le peuple!).