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 father of AsciiDoc) on DocBook

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


Donald E. Knuth

Get back to the content

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

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'

“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"

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.
asciidoc-processor
AsciiDoc processing
export-icon

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

Ruby gem
asciidoctor-org-writers-guide

Side by side

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
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 (con’t)

    ...
    <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 (and going)

            ...
            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."

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

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

> **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

Hmm, can’t seem to cover all the requirements :(

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

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


Anders Nawroth, Neo4j

Preview the big picture

asciidoc-processor
AsciiDoc processing
live-preview
Editing AsciiDoc with live preview

AsciiDoc on Java

asciidoctor-java
Asciidoctor Java integration
asciidoctor-java-usage
Asciidoctor Java build plugins

Who’s on board?

asciidoc-github
GitHub supports AsciiDoc!

“Pull-requestable” docs

pull-requestable-docs
Fork and edit this file

Evolving AsciiDoc

Scaling your docs

Notes
  • work inside out: evolve your document
  • back to basics: it’s just text mate
  • forward to publishing: drop the <>, but not the semantics

Drop the </>, but not the semantics

Notes
  • "You can drop those damn angled brackets, but you don’t have to drop the semantics."
  • "You get to work with a syntax a human can actually edit, _efficiently."
  • "At any point, you can convert it to DocBook as a common exchange format.
  • "DocBook is the "no lock-in" exit path for AsciiDoc."
  • "You decide AsciiDoc doesn’t work out, you can bail on it without losing a word."
  • "What’s to lose?"

Zen is…

Notes
  • "AsciiDoc is easy to read in raw form."
  • "It’s also easy to proof and edit."
  • "The punctuation was chosen to look like what it means."
  • "Only requires a text editor to read or write."

“It’s just text, mate”

Enjoy writing zen!

nfjs-magazine-cover