Dans cet épisode, Maxime et Guillaume discutent des langages de markup - en particulier Asciidoctor - pour l’écriture de documentation. Quels sont leurs bénéfices, quels outils et flux de travail adopter ? On y aborde ces questions.

Enregistré le 31 mars 2016

Téléchargement de l’épisode LesCastCodeurs-Episode-144.mp3

Interview

Ta vie, ton oeuvre

Maxime Gréau
@mgreau
eXo Platform

Guillaume Scheibel
@g_scheibel
Expedia

Markup et documentation

Qu’est-ce qu’un langage de markup ?
Pourquoi est-ce mieux, quels sont les avantages ?

HTML
XML

AsciiDoc / Asciidoctor

LaTeX
Docbook

Qu’est-ce qu’AsciiDoc ?
Quelles sont ses caractéristiques uniques
Qu’est-ce qu’Asciidoctor ?

AsciiDoc
Asciidoctor

Comparaison avec Markdown
Comparaison avec Docbook

Markdown
WYSIWYG

Une idée par ligne
Une idée par ligne - le retour d’expérience

En pratique

Qu’est-ce que j’installe ?

Un blog en Français décrivant tous les outils pour débuter

Google Chrome plugin: Asciidoctor.js Live Preview
Firefox plugin: Asciidoctor.ja Live Preview
Asciidoctor Gist

Conteneur Docker pour Asciidoctor
Maven Plugin
Gradle Plugin
Ant Task

Comment j’apprends ?

Documentation Asciidoctor
L’antisèche
La bible
Comparaison AsciiDoc vs Markdown par l’équipe Asciidoctor

Comment est-ce que j’édite ?
Les éditeurs disponibles
La boucle de retour écriture / visualisation (locale ou en ligne)

Atom
Bracket
IntelliJ Eclipse
Vim folding

Convertir sa documentation existante

DocbookRx (docbook vers AsciiDoc)
docbook2asciidoc (Docbook vers AsciiDoc) via XSLT
Kramdown pour AsciiDoc
Markdown to AsciiDoc
Pandoc
Google Docs vers AsciiDoc

Comment gérer les modifications concurrentes et les commentaires (à la Microsoft Word et LibreOffice)

Écrire de la documentation

Quels sont les avantages
Comment convaincre les non-développeurs d’utiliser Asciidoctor ?
La composition et la réutilisation de morceaux de documentation

Les autres cas d’utilisation

Écrire un livre

Écrire un livre en AsciiDoc avec InfoQ
Enterprise Web Development: From Desktop to Mobile écrit en AsciiDoc avec O’Reilly - source du livre en AsciiDoc
Pro Git v2 (FR) - source du livre en AsciiDoc

Un blog

HubPress.io
Jekyll AsciiDoc plugin et son quickstart
Le code du site web hibernate.org
Le code du blog de l’équipe Hibernate

Les présentations

reveal.js avec Asciidoctor
dzslides avec Asciidoctor
deckjs avec Asciidoctor
Bespoke avec Asciidoctor

Exemple de présentation de Maxime en dzslides + Asciidoctor - source

Quelques points précis

Les additions (formules mathématiques, schémas, etc)
Les diagrammes

Comment contribuer

Communauté française importante
Compte Github

  • Ruby -> core
  • Java -> asciidoctorJ wrapper via JRuby
  • Javascript -> asciidoctor.js
  • CoffeeScript -> plugin Atom

Nous contacter

Contactez-nous via twitter https://twitter.com/lescastcodeurs
sur le groupe Google https://groups.google.com/group/lescastcodeurs
ou sur le site web https://lescastcodeurs.com/
Flattr-ez nous (dons) sur https://lescastcodeurs.com/
En savoir plus sur le sponsoring ? sponsors@lescastcodeurs.com