Doctor, Doctor, my docs aren’t doing well. Can I get some Asciidoctor pills?

Working software over comprehensive documentation.


Agile Manifesto
Notes
  • "write only what gives value, drop the other things"
Agile Development Poster 2.0
Notes
  • "not waste our time formatting text or final layout"
  • "with collaboration"
  • "need a way to treat as code/tests/…"
handshake
Collaboration

Source Code

java 6
Notes
  • "javadoc"

Test

camera test
Notes
  • "ensures that we are deliverying what our customers need"
  • "docs like User Stories with Acceptance criteria, scenarios, fixtures …"

Environment’s Configuration

database
Notes
  • "thanks of puppet or chef, our environment’s configuration (that is server topology, …) is Agile and can acts as docs"

Documentation

System Binary icon

Mergeable

$ binary: git merge fix-village
warning: Cannot merge binary files: quijote.doc (HEAD vs. fix-village)

Auto-merging quijote.doc
CONFLICT (content): Merge conflict in quijote.doc
Automatic merge failed; fix conflicts and then commit the result.
$ binary: git diff master..fix-village
diff --git a/quijote.doc b/quijote.doc
index 4d7a47b..c8a6206 100644
Binary files a/quijote.doc and b/quijote.doc differ
formats
Start a Formatting War
Notes
  • "having multiple files means a manual process of copy paste which will be a headache because of formats"
  • "example of copying from web to doc, we only want contents not format"
track
Traceable
Notes
  • "given an element (can be code, test, document, an issue) I want to know all changes to that element and all releated modifications with the change", for example given an issue I want to which code was affected, which documents were touched, tests, …

Responsive

responsive
ballon
We need a lightweight way to write documentation
Notes
  • "fast to write (no change of context)"
  • "no worries about format, style or layout"

Lightweight markup languages

content + metadata

Notes
  • "example of markup languages for documentation markdown, textile, mediawiki, docbook, and of course AsciiDoc"
  • "treat as code so we will take advantage of tools and methodologies used for code development (SCM)"

“It’s just plain text.”

Notes
  • "AsciiDoc is easy to read in raw form, needs your favourite text editor and SCM without problem."

Rendered Document

render

DocBook

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book lang="en">
    <bookinfo>
        <title>Document Title</title>
        <date>2013-01-01</date>
        <author>
            <firstname>Doc</firstname>
            <surname>Writer</surname>
            <email>doc@asciidoc.org</email>
        </author>
        <authorinitials>DW</authorinitials>
        <revhistory>
            <revision>
                <revnumber>1.0</revnumber>
                <date>2013-01-01</date>
                <authorinitials>DW</authorinitials>
                <revremark>Initial version</revremark>
            </revision>
        </revhistory>
    </bookinfo>
    ...

DocBook (and going…)

    ...
    <preface>
        <title></title>
        <simpara>
           <ulink url="http://asciidoc.org">AsciiDoc</ulink> is a
           lightweight markup language.
        </simpara>
        <simpara>
            This is the optional preamble (an untitled section body).
            Useful for writing simple sectionless documents consisting
            only of a preamble.
        </simpara>
        <note>
            <simpara>
                The abstract, preface, appendix, bibliography, glossary
                and index section titles are significant
                (<emphasis>specialsections</emphasis>).
            </simpara>
        </note>
    </preface>
    <chapter id="_first_section">
        <title>First section</title>
        <simpara>
            ...

DocBook (at last!)

            ...
            Document sections start at <emphasis role="strong">level
            1</emphasis> and can nest four levels deep.
        </simpara>
        <itemizedlist>
            <listitem>
                <simpara>Item 1</simpara>
            </listitem>
            <listitem>
                <simpara>Item 2</simpara>
            </listitem>
        </itemizedlist>
    </chapter>
</book>

DocBook is nice, but (like XML) it is not meant for editing nor for merging changes (by humans).


Dag Wieers
Notes
  • "it is inhumane to write/maintain/read from this"

Markdown

# Document Title

[AsciiDoc](http://asciidoc.org) is a lightweight markup language.

This is the optional preamble (an untitled section body). Useful for
writing simple sectionless documents consisting only of a preamble.

<div class="note">
  <h5>Note</h5>
  <p>The abstract, preface, appendix, bibliography, glossary and index
  section titles are significant (<em>specialsections</em>).</p>
</div>

## First section

Document sections start at **level 1** and can nest four levels deep.

* Item 1
* Item 2

{% highlight ruby %}
puts 'Hello, World!'
{% endhighlight %}
Notes
  • "better but note that we are embedding html tags (presentation), and Markdown works pretty well for issues, small docs, … but does not offers "
  • "capabilities for more complex structures like toc, refs to other docs, …"

AsciiDoc

= Document Title
Doc Writer <doc@asciidoc.org>
v1.0, 2013-01-01: Initial version

http://asciidoc.org[AsciiDoc] is a lightweight markup language.

This is the optional preamble (an untitled section body), useful for
writing simple sectionless documents consisting only of a preamble.

NOTE: The abstract, preface, appendix, bibliography, glossary and
index section titles are significant (_specialsections_).

== First section

Document sections start at *level 1* and can nest four levels deep.

* Item 1
* Item 2

[source,ruby]
puts 'Hello, World!'
Notes
  • "links are written in form similar to HTML links, pretty intuitive even in plain text seems to have style"

Asciidoctor
A modern, open source implementation of AsciiDoc in Ruby

Ruby gem
Notes
  • "open source AsciiDoc renderer implemented in Ruby"
  • "which renders to html, docbook → pdf, ebook, or also custom templates (slim or haml)"
asciidoctor java
Asciidoctor Java integration
Notes
  • "you use in Java without noticing that internally are using a Ruby gem.

Example

import static org.asciidoctor.AttributesBuilder.attributes;
import static org.asciidoctor.OptionsBuilder.options;

...

Attributes attributes = attributes().backend("docbook").get();
Options options = options().inPlace(true).attributes(attributes).get();

String render = asciidoctor.renderFile("sample.asciidoc", options);

...

… and thanks of Java Integration

engine
Let’s render some documents
comic
Documentation is Diverse
Notes
  • "They have different purpose (presentation, know what to do, ensure quality)"
  • "Are written by different people and for different people"
close
As closest to writers as possible
Notes
  • "Docs should be as close to writer as possible so it can be updated at same time it is developed without having to change our context. Developers are involved almost in all documentation so it should be stored within project source code"
  • "Specifications can go to a separate module or root"
  • "Technical Designs go to same project and splitted with every component"
  • "User stories at ATDD project"
  • "Javadoc"
  • "Manuals (if technicals to same project and splitted with funcionalities)"
engine
Let’s see in Action
live
Documentation is a living system
Notes
  • "As living system you should take care of it, remember to treat as source code if you push code with a related issue id do the same, if you make code reviews do documentation reviews, …"
  • "If you are using CI or CD, docs can be rendered and published in every commit too, so everyone not only have the last working version but also the last approved documentation.""

Docs on the cloud

openshift

handshake
Anywhere Anytime Everybody
Notes
  • "You can write documentation anywhere (laptop, tablet, mobile), anytime because this year smartphones/tablets will sales of laptops and for everybody you do not need nothing special rather than a text editor."
stress
I have no TIME!!!
Notes
  • "people said the same with tests, and now all people believes in test"

Benefits

https://github.com/mojavelinux/docbookrx

cookie monster

Who’s doing AsciiDoc?

open
www.asciidoctor.org
github
https://github.com/lordofthejars/

Thanks!