Gestion de la documentation

[Jérémie]

Dans les projets pour lesquels j'ai travaillé, les spécifications et/ou le manuel utilisateur étaient gérés dans les fichiers Word… De mon point de vue c'est terrible. J'ai souvent évoqué le fait qu'il devait être possible de faire autrement, mais je n'ai jamais vraiment creusé le sujet.

Je me demande quelles sont les pratiques de l'industrie. En même temps, il ne s'agit pas de tomber dans des outils trop complexes ou trop usine à gaz.

De mon point de vue il faut pouvoir structurer les choses. Pouvoir sortir plusieurs documents à partir des mêmes sources (la dernière version du manuel, mais aussi un document décrivant les changements avec telle release ou telle change request). Parfois j'aimerais bien pouvoir ajouter dans le même système des informations techniques (à destination des développeurs, mais qui ne doivent être inclus dans les documents clients).

Tout ceci me fait penser à un bon système de Wiki (avec suffisamment de contraintes, de structures, d'organisation). Est-ce réaliste ? Existe-t-il d'autres produits (payant / libre) ?

Merci pour vos réponses,

Jérémie

[Antonio Goncalves]

Pas facile comme sujet. J'avais regardé des tas de trucs, et infine... on a fait du Confluence. L'idée c'est d'écrire des petites pages dans ton Confluence et d'utiliser le plugin Snippet ( https://marketplace.atlassian.com/plugins/com.atlassian.confluence.extra.snippet;jsessionid=4w18u0vg1jfg1dmgppngsi57v ) pour y intégrer des bouts de code de ton Subversion (le plugin date de 2010, pas sur qu'il y ai le support pour Git ;o)  Tu te retrouves ainsi avec des petits pages contenant du code toujours à jour (déjà, c'est pas mal, t'évite les copier/coller et le code qui évolue) que tu documentes.

Ensuite, pour ton guide du développeur, tu te prends une page Confluence où tu inclus et ordonnent tes pages grâce à la macro {include}. Et hop, t'as ton guide en ligne que tu peux aussi exporter en PDF.

Bon, c'est du Confluence, donc t'as aussi tous les inconvénients qui vont avec, mais ça fait le boulot. Je suis aussi preneur d'autres feedback

Antonio

2012/9/18 Jérémie <jebr...@gmail.com>

--
Vous recevez ce message, car vous êtes abonné au groupe Google Groupes lescastcodeurs.
Cette discussion peut être lue sur le Web à l'adresse https://groups.google.com/d/msg/lescastcodeurs/-/H9pe22MTNSgJ.
Pour envoyer un message à ce groupe, adressez un e-mail à lescast...@googlegroups.com.
Pour vous désabonner de ce groupe, envoyez un e-mail à l'adresse lescastcodeur...@googlegroups.com.
Pour plus d'options, consultez la page de ce groupe : http://groups.google.com/group/lescastcodeurs?hl=fr

--
Antonio Goncalves
Software architect and Java Champion

Web site | Twitter | LinkedIn | Paris JUG | Devoxx France

[Vincent Massol]

Salut Jérémie,

Tu viens de décrire précisément ce qu'on fait avec XWiki qui est un wiki structuré :)

http://xwiki.org

XWiki SAS (http://xwiki.com) met ça en place pour ses clients également.

-Vincent
Committer sur le projet open source XWiki
XWiki SAS CTO

[Nicolas Delsaux]

2012/9/18 Jérémie <jebr...@gmail.com>:

Tiens, c'est marrant, on s'est posé la même question récement, sans
pour autant trouver de réponse viable à mon goût.
En fait, la question de la documentation est multiple :
- est-ce que tu veux gérer la documentation interne à ton produit
(ses specs techniques/fonctionnelles, ses docs de test, ...) ?
- est-ce que tu veux gérer la documentation associée à ton produit
(doc d'install, doc d'utilisation, ...)
- est-ce que tu contrôle les logiciels utilisés pour produire la doc,
ou est-ce que tu importes des docouments provenant de systèmes tierces
(genre les specs écrites dans Google Documents) ?

Tout ça, ça fait du domaine de la doc un truc sacrément complexe, pour
lequel (après avoir lu les contributions d'Antonio et de Vincent) je
regrette de devoir le dire, je trouve que le wiki n'est pas assez
structurant .. enfin, structurant, ça n'est pas le mot, mais je ne
n'en ai pas de meilleur.
En fait, la question qui me taraude, c'est de garantir l'adéquation de
la doc avec le logiciel, c'est-à-dire garantir la traçabliité totale
d'une fonctionnalité du produit, en fait. Je reprend doucement.
Si ma doc est bien en accord avec le code de mon logiciel, c'est bien
parce que les deux livrables (la doc et le code) sont bien
synchronisés, exact ? Ces mêmes livrables qui sont dépendants d'autres
livrables (le code dépend en fait de la spec qui est une forme de
doc). Donc en théorie je ne pourrais produire le code qu'après la
validation de la spéc (me parlez pas agile/toussa... ça change rien au
problème de la nécessité d'une spéc avant le code, juste des questions
sur la nature/la taille de la spéc).
Bref, si je voulais me toucher la nouille, je dirais que quand je
livre l'artefact dqu'est le code, il a une dépendance (aoui oui, au
sens le plus maven du terme) RELEASE vers sa spéc. Et quand je livre
mon produit final, il a lui une dépendance RELEASE vers le code ET
vers la doc.
Dit comme ça, on comprend bien je trouve les enchaînements et les
parallélismes de ce que peut être le développement.
On comprend bien aussi qu'il serait facile de mettre la doc dans un
gestionnaire de source quelconque, et de la livrer avec le code de
cette façon (éventuellement les versions spécifiques PDF/Web/...
pourraient être produites lors du build du produit final).
Limite d'ailleurs qu'utiliser les outils de génération de site web
statique (genre celui qu'Emmanuel B nous vend tous les jours ou
presque ... Awestruct) serait une bonne idée (pour peu que les
rédacteurs de doc puissent entrer dans le moule, ce qui ne semble pas
le cas dans ma boîte).
Mais bon, tout ça n'est qu'une version modernisée d'un
amven-docbook-plugin, j'ai l'impression. Du coup, je trouve le tout un
peu inutile ...
En fait, je suis aussi preneur de toute idée un peu sympathique sur le sujet.

--
Nicolas Delsaux

[ehsavoie]

Perso à chaque fois on est parti sur un wiki car ca semble ideal et à
chaque fois ca dégénère car il faut qqun pour gérer le truc (ce que ne
font presque jamais les devs) :( et donc assez rapidement on se
retrouve avec des docs incomplètes, pas à jour de partout etc. MAIS je
n'ai jamais essayé un XWiki pour ça ;o)
Sinon y a http://arrenbrecht.ch/jcite/ JCite pour avoir de la doc
technique qui soit 'cohérente' avec le code. J'avoue avoir été emballé
par l'idée mais ne jamais avoir pris le temps d'y passer.


----------
Emmanuel Hugonnet
http://www.ehsavoie.com
http://twitter.com/ehsavoie


2012/9/18 Vincent Massol <vin...@massol.net>:

> --
> Vous recevez ce message, car vous êtes abonné au groupe Google Groupes lescastcodeurs.

[Antonio Goncalves]

Nous on avait même poussé le vice à jeter un oeil à tout ce qui tourne autour de DITA ( http://fr.wikipedia.org/wiki/Darwin_Information_Typing_Architecture )... et on a vite laissé tomber. Structurer de la doc, c'est pas facile.

Antonio

2012/9/18 ehsavoie <emmanuel...@gmail.com>

[Denis Sanchez]

Salut

j'ai utilisé plusieurs solutions, 

un site google, 

un googleDoc afin que le client et nous puissions modifier en même temps et faire du travail collaboratif.

Et carrément un site style drupal ou spip monté rapidement pour juste déposer de la doc et joindre des fichiers des captures d'écrans et faire le lien depuis l'application vers l'url contenant l'aide.

Une fois que le site est fait, les articles sont modifiables par le client, il peut ainsi mettre à jour facilement le manuel utilisateur.

Denis SANCHEZ
Edition - Informatique opérationnelle
VIF
Tél. +33 (0)2 51 89 12 40
Fax +33 (0)2 51 89 12 79
denis....@vif.fr
www.vif.fr

Vidéo : Agrovif 2012 en 2 minutes

--
Vous recevez ce message, car vous êtes abonné au groupe Google Groupes lescastcodeurs.

[Vincent Massol]

Salut Nicolas,

Pour l'adequation entre doc et soft, xwiki propose par ex 2 extensions (c comme ca qu'on appelle nos plugins) pour synchroniser ton contenu dans ton SCM (on fournit Subversion et Git).

Donc l'idee est de:
* utiliser le wiki pour ecrire, faire des liens, utiliser des macros, etc car c plus facile que sur notepad et ca fournit bcp bcp plus de possilbites (jusqu'a avoir une doc executable - demande a guillaume laforge sur son idee de doc groovy executable avec xwiki).
* gerer ca en conf (SCM) pour etre synchro avec le code source de ton logiciel.

- Git: http://extensions.xwiki.org/xwiki/bin/view/Extension/GitHubApp
- SVN: http://extensions.xwiki.org/xwiki/bin/view/Extension/SVN+Application

Pour info c'est comme ca qu'on travaille chez XWiki SAS pour nos projets clients.

Merci
-Vincent

PS: Je suis en train de travailler sur un storage next gen pour XWiki ou tu pourras directement choisir Git par ex comme storage. Mais ca c'est du futur un peu lointain… ;)

[Nicolas CHAPIN]

Vaste question sur laquelle on planche en ce moment chez nous.

Plusieurs problèmes

1. Les contributeurs (va faire sortir la MOA de word, et encore s'ils arrivent à l'utiliser correctement)
2. Les cycle de vie des différents documents (Les specs vont suivre un cycle majeur/evol, les manuels d'installation vont suivre un cycle à la release près, les manuels d'exploit devraient être une KB)
3. Les limiter les problèmes de report entre les différentes versions surtout si tu bosses sur plusieurs versions en parallèles.
4. Le format de livraison (si tu es en mode prestation)

Bref, on n'a pas encore trouvé la solution idéale. Et je ne parle pas des clients bureaucratiques à l'absurde.

Le wiki est une approche viable si celui que tu choisis te permet de dupliquer des branches de pages d'un coup genre spec/1.1=>spec/1.2.

Pour la gestion à partir du SCM, on envisage l'utilisation de docbook qui permet ensuite de fournir un joli PDF aux clients :). Mais n'importe quel générateur statique peut aider (ex: http://johnmacfarlane.net/pandoc/)

Dans l'idéal je vois 3 buckets de documents:

1. Les documents de spécifications qui peuvent êtres gérés à partir du SCM ou dans un wiki.
2. Les documents techniques (DC, DAT, MIS, etc.) qui sont gérés à partir du SCM.
   
3. Les documents d'exploitation qui sont gérés dans un wiki parce qu'ils sont la mémoire de la vie réelle du système.

Mais j'avoue que je ferais volontier une gaterie à celui qui me sortira la solution ultime, que sa dépendance soit bénie à la 42ième génération.

--

Vous recevez ce message, car vous êtes abonné au groupe Google Groupes lescastcodeurs.

Cette discussion peut être lue sur le Web à l'adresse https://groups.google.com/d/msg/lescastcodeurs/-/H9pe22MTNSgJ.

Pour envoyer un message à ce groupe, adressez un e-mail à lescast...@googlegroups.com.
Pour vous désabonner de ce groupe, envoyez un e-mail à l'adresse lescastcodeur...@googlegroups.com.
Pour plus d'options, consultez la page de ce groupe :

http://groups.google.com/group/lescastcodeurs?hl=fr

--
Nicolas CHAPIN -- Software architect
Mail: nch...@gfi.fr
Mobile: +33 (0)6 83 08 55 50

Web: http://www.gfi.fr/

[Nicolas Labrot]

On utilise DITA pour documenter nos produits, le tout sous GIT avec en sortie une transfo HTML / PDF couplé à Maven. Effectivement structurer et rédiger la doc utilisateur c'est un métier.

Je suis sceptique sur l’utilisation d'un wiki surtout quand le but est de créer un livrable pour le client. Mais peut etre que xwiki offre les outils de structuration et de publication ;)

2012/9/18 Antonio Goncalves <antonio....@gmail.com>

[Frédéric Bouquet]

Hello,

J'ai un ancien copain qui bossais sur un outil qui permettait
justement de structurer la documentation comem des modules que tu
agrégeais pour former ta doc.
Je viens de retrouver cet article de présentation :
http://www.framasoft.net/article4650.html
Le site officiel : http://www.kolekti.org/

A voir comment ça a évolué, à l'époque où j'avasi regardé, il fallait
travailler en XML et l'utilisation n'était pas très simple. Cela a
probablement évolué depuis

Le 18 septembre 2012 16:46, Jérémie <jebr...@gmail.com> a écrit :

> --
> Vous recevez ce message, car vous êtes abonné au groupe Google Groupes
> lescastcodeurs.

> Cette discussion peut être lue sur le Web à l'adresse
> https://groups.google.com/d/msg/lescastcodeurs/-/H9pe22MTNSgJ.

> Pour envoyer un message à ce groupe, adressez un e-mail à
> lescast...@googlegroups.com.
> Pour vous désabonner de ce groupe, envoyez un e-mail à l'adresse
> lescastcodeur...@googlegroups.com.
> Pour plus d'options, consultez la page de ce groupe :
> http://groups.google.com/group/lescastcodeurs?hl=fr



--

Frédéric Bouquet
Twitter/Github : bouquetf
http://www.espacedefouille.org/

[Olivier Jaquemet]

Je vais t'orienter vers une précédente discussion de la ML qui concernait un sujet similaire :

https://groups.google.com/forum/?fromgroups=#!topic/lescastcodeurs/z3p_dkcTa28 

Une des piste que j'évoquais était celle retenu par Neo4J, en synthèse : les specs, la doc, les exemple, tout est dans le code et fait partie du processus de build . impossible de passer à coté, autant sur la mise à jour par les développeurs que sur la validation et l'utilisation par les utilisateurs finaux.

J'aurais bien aimer t'orienter vers une vidéo ou Peter Neubauer présente cette archi, mais malheureusement je n'en ai pas :/

Le PDF de sa présentation "Test Driven Bloggin or How a Wiki Almost Killed My Startup" est accessible mais comme c'était à partir d'un prezzi le rendu n'est pas top ... : 

http://cdn.oreillystatic.com/en/assets/1/event/80/Test%20Driven%20Blogging%20or%20how%20a%20wiki%20almost%20killed%20my%20startup%20Presentation.pdf

2012/9/18 Jérémie <jebr...@gmail.com>

--

[Dimitri BAELI]

Pour de la doc liée à un développement (et qui donc doit suivre les branches de développement). Ce que j'ai vu (et pratiqué) de mieux à ce jour est l'outil développé par Julien Viet qui s'appeller "wikbook". 

L'idée magique est d'avoir des fichiers en .wiki (format xwiki, confluence, ou autre) dans le code source et l'outillage pour générer la doc en pdf (ou autre) au build (si besoin) est fourni. Par exemple, il est possible de faire des insertions de bout de vrai code (et de la bonne branche !). Plus pas mal de petites choses intéressantes.

La documentation devient un livrable du projet, au même niveau que les binaires. C'est très structurant !

Voir le Readme pour quelques liens https://github.com/vietj/wikbook/blob/master/README.md 

J'encourage les curieux à essayer, c'est un petit bijou bien caché.

Dimitri

2012/9/18 Olivier Jaquemet <olivier....@gmail.com>

[Pierre-Yves Ricau]

Quand on cherche à tendre vers le développement sous forme de feature branches, et qu'on prends le temps de soigner son arbre de commits gits, on en arrive souvent à "1 commit  = 1 feature". Et idéalement, ce commit contient spec + doc + code + tests. Au delà de simplement "mettre à jour la spec/doc", pour moi l'important est d'exprimer ce qui a changé et pourquoi ça a changé, et pouvoir facilement le visualiser.

Ce qui signifie qu'il faut banir tout format binaire du scm (word, open office, pdf).

C'est là où GitHub devient intéressant, car la UI web permet de visualiser plutôt bien des documents écrits dans des formats texte (markdown etc). Plus besoin de transformations vers PDF pour visualiser la spec. Et qu'on ne me dise pas qu'un "MOA" n'est pas capable d'aller sur GitHub pour peu qu'on le guide.

--
Pierre-Yves Ricau

http://www.piwai.info

[ehsavoie]

Bien d'accord avec Dimitri.
Il ne manque que l'intégration avec JCite pour valider les portions de
code des exemples et ca serait le nirvana ;)

----------
Emmanuel Hugonnet
http://www.ehsavoie.com
http://twitter.com/ehsavoie

2012/9/18 Dimitri BAELI <dba...@gmail.com>:

[Clement Escoffier]

Bonjour,

Alors pour ma part j'utilise 2 techno:

- Les Maven sites avec Fluido (Twitter Bootstrap) et Markdown: pour la doc technique.  Avantage clair…. ça se release avec le code, donc ça suit les changements. J'utilise ça sur github page dans mes projets open source. C'est assez simple d'édition (markdown) et ça rend pas trop mal...

- XWiki / Confluence pour le reste : mode plus collaboratif (spec), mise en plage plus poussée. J'exporte régulièrement en pdf.

J'avoue que pour l'instant j'utilisais Confluence… mais avec mon retour en France, je pense migrer a X-Wiki pour soutenir la société Eponyme.

Clement

[Vincent Massol]

Salut Clement,

On Sep 19, 2012, at 9:53 AM, Clement Escoffier <clement....@gmail.com> wrote:

> Bonjour,
>
> Alors pour ma part j'utilise 2 techno:
> - Les Maven sites avec Fluido (Twitter Bootstrap) et Markdown: pour la doc technique. Avantage clair…. ça se release avec le code, donc ça suit les changements. J'utilise ça sur github page dans mes projets open source. C'est assez simple d'édition (markdown) et ça rend pas trop mal...
> - XWiki / Confluence pour le reste : mode plus collaboratif (spec), mise en plage plus poussée. J'exporte régulièrement en pdf.
>
> J'avoue que pour l'instant j'utilisais Confluence… mais avec mon retour en France, je pense migrer a X-Wiki pour soutenir la société Eponyme.

C'est bien ca! Beau geste patriotique… :) (bon je prefere penser que c'est parce que XWiki est bien plus puissant).

La communaute XWiki est super active et on sera content de t'aider/conseiller si besoin (IRC, mailing list)!

Merci
-Vincent

[jcsirot]

Chez nous la documentation utilisateur est en LaTeX et le source est dans le même dépot que le code du produit. Un PDF est généré lors de la compilation du projet avec un plugin maven développé en interne.

Les points positifs que je trouve à cette méthode :

- on peut utiliser les mécanisme de gestion de dépendances (de maven en l’occurrence mais ça peut marcher avec d'autres) pour découper la documentation en modules réutilisables

- la notion de DONE comprend la modification de la doc, on peut voir dans le log du commit si elle a été faite avant de fermer le ticket

- la doc est versionée avec le produit (c'est important pour moi qui fait des produits de sécurité)

- un document LaTeX c'est joli

Les point négatifs :

- il faut que les rédacteurs de la doc acceptent de faire du LaTeX, ce n'est pas toujours gagné

- LaTeX oblige, la mise en forme est parfois complexe

[Frédéric Bouquet]

Parmi les solutions proposées, combien les utilisent avec des équipes
de doc (technique ou non) qui ne sont pas des développeurs à la base ?
Je pense que dans ce cas, un outil type wiki est plutôt pas mal, XWiki
semble plutôt prometteur. Seule contrainte qui m'a été remontée par
rapport à ça, c'est que ce type d'infra est gérée par une équipe
d'admins/devs php qui galèrent en général à intégrer ces outils dans
une infrastructure souvent full php. Est-ce que vous avez aussi ce
genre de contraintes de votre côté ?

Sinon, des retours sur l'utilisation de docbook ? On l'utilise il me
semble pas mal dans les projets de livres (jenkins book, hgbook pour
ceux auxquels j'ai participé). Quid des éditeurs wysiwyg ? Utilisable
par des non développeurs ?

Le 19 septembre 2012 11:15, Alban Dericbourg <al...@dericbourg.name> a écrit :
> Hello,

>
>
> On Wednesday, September 19, 2012 10:18:06 AM UTC+2, jcsirot wrote:
>>
>> Chez nous la documentation utilisateur est en LaTeX et le source est dans
>> le même dépot que le code du produit. Un PDF est généré lors de la
>> compilation du projet avec un plugin maven développé en interne.
>>

>> Les point négatifs :
>> - il faut que les rédacteurs de la doc acceptent de faire du LaTeX, ce
>> n'est pas toujours gagné
>> - LaTeX oblige, la mise en forme est parfois complexe
>>
>

> Pour avoir déjà essayé, je n'ai pas réussi à faire ça depuis... mon projet
> de fin d'étude à l'école.
> Convaincu que LaTeX est une des bonnes solutions pour ce genre de choses
> (yaka voir le résultat), comment cela a été proposé aux rédacteurs ? Si
> c'est de la doc utilisateur, c'est donc plutôt des gens fonctionnels qui la
> rédigent donc (attention cliché) plutôt des gens qui utilisent Word pour
> faire du texte et Excel pour faire une base de données (sic).
>
> Du coup, je suis plus intrigué et interrogatif quant à la conduite du
> changement / adoption de la solution que dans le choix de celle-ci.
> Ça s'est passé comment ? Et ça se passe comment après X temps d'utilisation
> ?

>
> --
> Vous recevez ce message, car vous êtes abonné au groupe Google Groupes
> lescastcodeurs.
> Cette discussion peut être lue sur le Web à l'adresse

> https://groups.google.com/d/msg/lescastcodeurs/-/_xPivpc-aLIJ.

>
> Pour envoyer un message à ce groupe, adressez un e-mail à
> lescast...@googlegroups.com.
> Pour vous désabonner de ce groupe, envoyez un e-mail à l'adresse
> lescastcodeur...@googlegroups.com.
> Pour plus d'options, consultez la page de ce groupe :
> http://groups.google.com/group/lescastcodeurs?hl=fr



--

[Vincent Massol]

Hello,

On Sep 19, 2012, at 11:55 AM, Frédéric Bouquet <bouquet....@gmail.com> wrote:

> Parmi les solutions proposées, combien les utilisent avec des équipes
> de doc (technique ou non) qui ne sont pas des développeurs à la base ?
> Je pense que dans ce cas, un outil type wiki est plutôt pas mal, XWiki
> semble plutôt prometteur. Seule contrainte qui m'a été remontée par
> rapport à ça, c'est que ce type d'infra est gérée par une équipe
> d'admins/devs php qui galèrent en général à intégrer ces outils dans
> une infrastructure souvent full php. Est-ce que vous avez aussi ce
> genre de contraintes de votre côté ?

Pour XWiki, tu peux resoudre ce probleme en trouvant un hebergeur qui supporte XWiki.

Par exemple XWiki SAS avec XWiki Cloud ;)
http://www.xwiki.com/xwiki/bin/view/Offer/XWikiCloud

Apres si tu veux l'heberger toi meme oui il te faut une equipe d'infra qui sait gerer des serveurs d'app java.

> Sinon, des retours sur l'utilisation de docbook ? On l'utilise il me
> semble pas mal dans les projets de livres (jenkins book, hgbook pour
> ceux auxquels j'ai participé). Quid des éditeurs wysiwyg ? Utilisable
> par des non développeurs ?

Pour info XWiki a egalement un support de docbook. XWiki le supporte comme format natif en input et surtout (ce qui me parait plus interessant) en sortie (tu peux exporter ta page en docbook). En revanche c'est assez beta comme fonctionnalite car le parseur et renderer Docbook qu'on utilise sont pas super secs… Ceci dit un export PDF me parait plus interessant en sortie.

Pour ecrire un livre j'aimerais bien que XWiki soit utilisé car je pense qu'on est pas loin d'avoir une super solution:
- On peut deja faire des export PDF qui sont assez jolis et multipages
- On a la possibilite de mettre des annotations sur le contenu (pour faire des reviews du livre)
- On peut travailler a plusieurs

-Vincent

[Dimitri]

Emmanuel,
Pas besoin de JCite dans wikbook ! Le code des portions de doc est pris par référence, donc il est vérifié, et garanti comme venant du code !

-------------------------------
Dimitri BAELI

[ehsavoie]

J'avais loupé ce point. De la balle !!!!!
Bon reste plus qu'à convaincre le reste de la team

----------
Emmanuel Hugonnet
http://www.ehsavoie.com
http://twitter.com/ehsavoie

2012/9/19 Dimitri <dba...@gmail.com>:

[Julien Ponge]

Dans la série léger et simple, il existe Pandoc qui donne d'excellent
résultats : http://johnmacfarlane.net/pandoc/

Je suis assez fan de la combinaison markdown + export html / pdf /
ebook avec utilisation de Pygments pour la coloration syntaxique
d'extraits de code. Pour tout vous dire Pandoc propose meme un export
Word ... et il est irréprochable. Il m'arrive de préparer des
documents de travail en Markdown et de les exporter en Word, juste
parceque ce workflow me va mieux et que la sortie est propre.

Pandoc n'est pas miracle, mais pour ceux qui cherchent à faire du
Markdown, ne veulent pas dégainer Docbook, ou encore ne sont pas
intéressés pas un wiki, c'est plus que pas mal. Pro Git de Scott
Chacon a été rédigé de la sorte.

Il y a aussi AsciiDoc dans la même veine, avec un export Docbook qui a
l'air de bien marcher et qui se rapproche du projet de Julien de
Marseille. JBoss semble apprécier cette solution. J'ai essayé quelques
fois, mais j'avoue préférer une syntaxe Markdown.

Et puis les toolchains Docbook me donnent la nausée. Je suis
admiratifs devant ceux qui ont réussi à rédiger des documentations
complètes avec cette patée de XML.

My 2 cents

- Julien

[Julien Ponge]

Veuillez au passage excuser les fotes d'ortograffe qui émaillent cette missive.

/me needs sleep

2012/9/19 Julien Ponge <julien...@gmail.com>:

[Dimitri]

Pour markdown dans wikbook ça dépend du suppprt xwiki dans le domaine, car c'est le moteur embarqué.

J'ai pas regardé si c'était supporté.
Vincent, une idée ?

-------------------------------
Dimitri BAELI

> --
> Vous recevez ce message, car vous êtes abonné au groupe Google Groupes lescastcodeurs.

[Vincent Massol]

On Sep 19, 2012, at 2:12 PM, Dimitri <dba...@gmail.com> wrote:

> Pour markdown dans wikbook ça dépend du suppprt xwiki dans le domaine, car c'est le moteur embarqué.
>
> J'ai pas regardé si c'était supporté.
> Vincent, une idée ?

C'est supporté (grace a Emmanuel qui a voulu ecrire les pages de preparation du podcast LCC en markdown sur notre wiki qui est XWiki ;)).

-Vincent

[Dimitri BAELI]

   Donc il y a moyen d'avoir markdown dans wikbook, et donc de profiter des pages markdown dans git hub et un outillage maven pour produire des pdfs.

   Mazette !

Dimitri

2012/9/19 Vincent Massol <vin...@massol.net>

[Julien Ponge]

J'aimerai bien voir des exemples de sorties PDF / HTML / whatever avec
les sources histoire de me faire une idée ;-)

2012/9/19 Dimitri BAELI <dba...@gmail.com>:

[ehsavoie]

Le site de crash ;o)
http://julienviet.com/crash/#doc

----------
Emmanuel Hugonnet
http://www.ehsavoie.com
http://twitter.com/ehsavoie

2012/9/19 Julien Ponge <julien...@gmail.com>:

[Dimitri]

Regarde le lien donné au départ dans le README.md du projet wikbook, il pointe sur la doc de crash par exemple.

Il y a même la génération d'html (navigation statique avec boostrap).

-------------------------------
Dimitri BAELI