Discover the zen of writing (Ascii)Docs

Writing

Write to write

Word processors are sabotaging
your writing

Notes
  • "Word processors are the real writer’s block."

“Just let me write, dammit!”

I was spending more time fixing syntax errors than I was writing the documentation.


Stuart Rackham (the creator of AsciiDoc) on DocBook

Get back to the content

Notes
  • "Content is king!"
  • "Use what you know."

The enjoyment of one’s tools is an essential ingredient of successful work.


Donald E. Knuth

“It’s just text, mate.”

Notes
  • "AsciiDoc is easy to read in raw form."
  • "It’s also easy to proof and edit."
  • "Only requires a text editor—your favorite text editor—to read and write"

Lightweight markup languages

                                           +yyyyyyyyyyyyyyyyyyyyyyo-
                                          `yNNNNNNNNNNNNNNNNNNNNNMMMNo`
                                        -:::::::::::::::::::::::`.:dMMN-
                                      oNMMMMMMMMMMMMMMMMMMMMMMMMMd/ sMMN`
                                     oMMm+:::::::::::::::::::::+MMM: NMM-
                                     sMMs                       MMMo NMM-
                                     sMMs                       MMMo NMM-
                                     sMMs `mMMMMMMMMMMMMMMMMMd  MMMo NMM-
                                     sMMs  `++++++++++++++++/`  MMMo NMM-
                                     sMMs `mMMMMMMMMMMMMMMMMMd  MMMo NMM-
                                     sMMs  .+++++++++++++++++`  MMMo NMM-
                                     sMMs `dmmmmmmmmmmmmmmmmmh  MMMo NMM-
                                     sMMs  ://///////////////.  MMMo NMM-
                                     sMMs `hmmmmmmmmmmmmmmmmms  MMMo NMM-
                                     sMMs  //////////////////-  MMMo NMM-
                                     sMMs `yddddddddddddddddds  MMMo NMM-
                                     sMMs  /yyyyyyyyyyyyyyyys/  MMMo NMM-
                                     sMMs `ohhhhhhhhhhhhhhhhho  MMMo NMM-
                                     sMMs                       MMMo dMN.
                                     sMMs                       MMMo  .`
                                     :MMMdhhhhhhhhhhhhhhhhhhhhhdMMN.
                                      .shmmmmmmmmmmmmmmmmmmmmmmmho.




       .o.                           o8o   o8o  oooooooooo.
      .888.                          `"'   `"'  `888'   `Y8b
     .8"888.      .oooo.o  .ooooo.  oooo  oooo   888      888  .ooooo.   .ooooo.
    .8' `888.    d88(  "8 d88' `"Y8 `888  `888   888      888 d88' `88b d88' `"Y8
   .88ooo8888.   `"Y88b.  888        888   888   888      888 888   888 888
  .8'     `888.  o.  )88b 888   .o8  888   888   888     d88' 888   888 888   .o8
 o88o     o8888o 8""888P' `Y8bod8P' o888o o888o o888bood8P'   `Y8bod8P' `Y8bod8P'

A lightweight, yet powerful text-based markup language and document generator.

Mild punctuation mild

Notes
  • "Mild punctuation, strong impact."

“Looks like what it means”

A paragraph is just a paragraph. No special syntax required.

This paragraph contains _emphasized_, *strong*, `monospaced` text.

This paragraph has `smart single quotes' and ``smart double quotes''.

The square of x can be written as x^2^.

We break at the end of this line +
to keep the text from overflowing.

The syntax

Let’s compare 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
  • "It’s plain text…I know this."

…to 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>
    ...

…to 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>
            ...

…to 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>
Notes
  • "I looked across the room, asked Are you writing in DocBook?"
  • "How did you know?"
  • "Because I can only pick out about 5 works in a see of syntax highlighted XML"

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


Dag Wieers
Notes
  • "Let me rephrase that for Dag."

Writing DocBook is just… inhumane

Notes
  • "AsciiDoc gets us back to what’s important, writing."

I’m amazed by AsciiDoc :-) It handles a lot of use cases well, and some other cases are still possible at least.

Neo4j project
Anders Nawroth

But I use Markdown to write my documention.


Most developers on GitHub

Let’s compare 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, intuitive to us

…to 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 %}

Markdown : 1st-grader :: Asciidoc : PhD student

Who’s doing AsciiDoc?

Processing AsciiDoc

asciidoc processor
AsciiDoc processor

𝔸sciidoctor
A modern, open source implementation of AsciiDoc in Ruby

Ruby gem
export icon

Built on Asciidoctor

asciidoctor org writers guide
asciidoctor org mobile view

Asciidoctor Stylesheet Factory

asciidoctor styles

Preview the big picture