Doc-As-Code

Documentación Continua

2019-05-19

Who I am?

Jorge Aguilera

https://jorge-aguilera.gitlab.io

Tutorial Asciidoctor (Amazon)

100

@jagedn

Freelance Java, Groovy developer

Speaker MadridGuG, Codemotion

Who are you ?

  • ¿ documentáis vuestros proyectos ?

  • Word, Excel, OpenOffice, …​

  • ¿ Confluence ?

  • ¿ os gusta documentar ?

Agenda

  • lo que veo a mi alrededor

  • doc-as-code

  • alternativas

    • Markdown

    • reStructuredText/Sphinx (Python)

    • Asciidoctor/Antora

  • ejemplos

  • WriteTheDocs

Joke

A mi alrededor

  • Documentos Word:

    • versión inicial o final

    • historial de cambios en la primera página …​ con v1.0, v1.1 …​ y ya

  • Word a Pdf …​ que no corresponden

  • Copy&Paste de código, XML de 200 líneas,

Demanda millonaria

Confluence

  • ¿ cuándo actualizas la documentación ?

  • ¿ lo revisa alguien ?

  • ¿ exportas a otros formatos ?

  • ¿ disfrutas documentando ?

Opinión Personal de un usuario básico

Agile

  • Principio TAGRI – “They Ain´t Gonna Read It” -, introducido por Scott Ambler. La idea básica es que muy poca de la documentación que es creada durante el desarrollo del software, realmente es leída por los interesados.

  • así que Agile me permite NO documentar…​

  • se debería documentar de forma ágil reflejando las necesidades reales de documentación de la audiencia interesada.

Doc-as-code

Un paso hacia la Documentación contínua

"Filosofía" orientada a usar las mismas herramientas y procesos que se usa para crear el software:

Doc-as-code

  • sólo texto plano, editable con un simple notepad

  • versionable, crear branch, hacer PR, merge, reviews (git)

  • "compilable" (si la docu no corresponde al software se rompe el Pipeline)

  • integrado con la misma infraestructura que el código (repositorio, editores, workflow, entrega)

Doc-as-code

Ventajas:

  • mismo entorno, mismas herramientas, mismo "lenguaje" (no de programación sino semántico)

  • avance alineado

  • motivado

Buzzwords (palabrejas)

  • Markdown, reStructuredText, asciidoc (lenguajes marcado)

  • Sphinx, Asciidoctor (generadores)

  • Hugo, Jbake, Jekyll (static blog)

  • ReadTheDocs, Antora (publish)

  • Apache, Nginx (servidor documentos)

Markdown

Titulo
------
Subtitulo
---------
*negrita*, _italica_

reStructureText

.. js:function:: $.getJSON(href, callback[, errback])

   :param string href: An URI to the location of the resource.
   :param callback: Gets called with the object.
   :param errback:
       Gets called in case the request fails. And a lot of other
       text so we need multiple lines.
   :throws SomeError: For whatever reason in that case.
   :returns: Something.

Sphinx & ReadTheDocs

  • Sphinx: generador

  • ReadTheDocs: hosting free

INFO

Muy populares (en el mundo python sobre todo)

Asciidoctor

generador multiformato (html, pdf, epub, revealjs, …​)

típico en static-site

Ruby

AsciidoctorJ, Maven, Gradle

Asciidoctor

Diagramas

Include de códigos

Html, Pdf, EPub, Slides, …​

Antora

generador (basado en asciidoctor) ideal para "producto"

multi-repo, multi-versions, etc

INFO

Muy populares (en el mundo Ruby y Java sobre todo)

Ejemplos: Presentacion

Esta presentación

Ejemplos: Arquitectura

Ejemplos: Proyecto

Ejemplos: Múltiples proyectos

Multi repo, multi version

Spring REST Docs

API alineado con la documentación

Write The Docs (doc-as-code)

arc42 & docToolChain

  • "plantilla" de documentos cubren todo el ciclo de vida de un producto

  • herramienta para unificar múltiples inputs (word, ppt, adoc) y generar múltiples outputs

Conclusiones

Q&A & Feedback

ContactFeedback

@jagedn

https://forms.gle/s6gzqtbp66Su7yRq6 https://forms.gle/s6gzqtbp66Su7yRq6

https://gitlab.com/puravida-software

https://www.linkedin.com/in/jagedn/

gracias multilingue