Better documentation with asciidoc and asciidoctor

2013 © Trivadis

BASEL BERN BRUGG LAUSANNE ZUERICH DUESSELDORF FRANKFURT A.M. FREIBURG I.BR. HAMBURG MUNICH STUTTGART VIENNA

2015 © Trivadis

Better documentation with AsciiDoc and

AsciiDoctor

Ulises Fasoli

07.03.2015Better documentation with asciidoc and asciidoctor

1

2013 © Trivadis2015 © Trivadis

AGENDA

1. Why documentation is important?

2. Documentation tools

3. AsciiDoc

4. AsciiDoctor

5. Tips and useful links

2 2015 © Trivadis

07.03.2015

Better documentation with asciidoc and asciidoctor


Why documentation is important?

3 2015 © Trivadis

07.03.2015



Why documentation is important?

4

Keep track of all aspects of an application

Improve quality of the software product

Ease the transfer of knowledge

The RTFM factor

2015 © Trivadis

07.03.2015



Some aspects in which documentation is beneficial

5

Server environments

Business rules

Databases/Files

Troubleshooting

Application installation / configuration

Code deployment / packaging

2015 © Trivadis

07.03.2015



AGENDA



3. AsciiDoc

4. AsciiDoctor


6 2015 © Trivadis

07.03.2015



Documentation tools

7 2015 © Trivadis

07.03.2015



Most commonly used tools for writing documentation

8

Plain text

Word processors (Microsoft Word, Open office, etc.)

DocBook

Markdown

Asciidoc

2015 © Trivadis

07.03.2015



Plain Text

9

Easy to write : “no fluff just stuff”

Integration with version control tools

Human readable

Just plain text : can be edited in any

environment without extra tools

2015 © Trivadis

07.03.2015



Plain Text : Disadvantages

10

Too simple

No formatting options

Concurrent edition

No document navigation

2015 © Trivadis

07.03.2015



Word processors

11

De facto standard for writing documentation

Offer a complete set of tools :

Spell /grammar check

Predefined styles

Drawing tools

…

2015 © Trivadis

07.03.2015



Word processors : disadvantages

12

Integrate poorly with source control systems

Do not handle source code syntax

highlighting

Formatting issues

Concurrent edition

No aggregation capabilities

Monolithic document approach

2015 © Trivadis

07.03.2015



Docbook

13 2015 © Trivadis

07.03.2015


Extensive set of formatting options

Multiple output formats :

HTML

PDF

Epub

Man pages

…

Customizable output (through CSS)


DocBook: disadvantages

14 2015 © Trivadis

07.03.2015


Verbose

Content polluted by tags

Readability issues

“Requires” and editor

Learning curve

“Writing in DocBook is just, inhumane.” Dan Allen


Markdown

15 2015 © Trivadis

07.03.2015


Lightweight markup language

Readability

Maturity of the project

Ubiquity


Markdown: disadvantages

16 2015 © Trivadis

07.03.2015


Not as complete as AsciiDoc

Multiple output formats not handled

natively

Fallback to HTML syntax (i.e.

anchors, tables)

“If Markdown is a 1st-grader, then AsciiDoc is PhD student”

Dan Allen


Documentation tools

17 2015 © Trivadis

07.03.2015



AGENDA



3. AsciiDoc

4. AsciiDoctor


18 2015 © Trivadis

07.03.2015



AsciiDoc

19 2015 © Trivadis

07.03.2015



AsciiDoc

20 2015 © Trivadis

07.03.2015


“Writing is hard.”

Or is it?

The Zen of AsciiDoc writing :

It’s readable

It’s concise

It’s comprehensive

It’s extensible

It produces beautiful output (HTML, DocBook, PDF, ePub and more)


AsciiDoc

21 2015 © Trivadis

07.03.2015


Lightweight markup language (plain text embellished with subtle markup)

Natural, readable syntax; it’s just text

Content is king philosophy

The beauty of AsciiDoc is that, like code, you can

use a multitude of tools to edit, but still have one,

versioned source.


DocBook vs Asciidoc sample

22 2015 © Trivadis

07.03.2015



DocBook vs Asciidoc sample…. continued

23 2015 © Trivadis

07.03.2015



What do you get with AsciiDoc ?

24

A plain-text writing format for :

authoring notes, articles, documentation, books, ebooks, web pages, slide decks, blog

posts, man pages...

A text processor and toolchain for translating AsciiDoc documents into various

formats (backends):

HTML

DocBook

PDF

ePub

…

2015 © Trivadis

07.03.2015



Asciidoc Basic document structure

25 2015 © Trivadis

07.03.2015


HEADER

FOOTER

Section

Section

Section

TOC


What can AsciiDoc can do?

26

Paragraphs

2015 © Trivadis

07.03.2015


Admonitions

Tip

Important

Warning

Caution

Paragraph



27

Formatted text

Bold

Italic

Monospace

..

2015 © Trivadis

07.03.2015




28

Section Titles (headings)

2015 © Trivadis

07.03.2015




29

Lists (up to 5 level nesting)

Unordered

Ordered

Labeled

2015 © Trivadis

07.03.2015


Unordered

(with title)

Nested

Ordered

Labeled



30

Links

2015 © Trivadis

07.03.2015


Checklists



31 2015 © Trivadis

07.03.2015


Images

Videos



32 2015 © Trivadis

07.03.2015


Tables



33 2015 © Trivadis

07.03.2015


Tables (CSV)



34 2015 © Trivadis

07.03.2015


Source code

Coderay

highlightjs

prettify

pygments



35

Diagrams

Ditaa

Graphviz dot

PlantUML

2015 © Trivadis

07.03.2015




36

More diagrams!

2015 © Trivadis

07.03.2015



What else can AsciiDoc do?

37 2015 © Trivadis

07.03.2015


Inclusion

Footnotes

Table of contents

Indexes

Musical notation

Mathematical formulas

Themes

Conditional content

…..


AGENDA



3. AsciiDoc

4. AsciiDoctor


38 2015 © Trivadis

07.03.2015



AsciiDoctor

39 2015 © Trivadis

07.03.2015



AsciiDoctor

40 2015 © Trivadis

07.03.2015


Fast text processor and publishing toolchain

Converts AsciiDoc content to

HTML5

DocBook

EPUB3

PDF

…

Written in Ruby but ported to the JVM (JRuby)

Out of the box with a complete set of templates, styles, etc.


AsciiDoctor maven plugin

41 2015 © Trivadis

07.03.2015


Portage of AsciiDoctor to the maven ecosystem

New functionality added regularly

Fast growing community


AsciiDoctor maven plugin (1)

42 2015 © Trivadis

07.03.2015


Define the plugin

Plug to a maven phase

Configure some options

Define output (backend)


AsciiDoctor maven plugin (2)

43 2015 © Trivadis

07.03.2015


Define a second execution

Define the additional

output format

Define the common

options for both executions


AsciiDoctor maven plugin : maven site integration

44 2015 © Trivadis

07.03.2015



AGENDA



3. AsciiDoc

4. AsciiDoctor


45 2015 © Trivadis

07.03.2015



Tips and useful links

46 2015 © Trivadis

07.03.2015



Some AsciiDoc tips / useful links

47

Separate your content when possible in files (use include macro)

Use conditional blocks when required (i.e. writing environment dependent

documentation)

Useful links:

Blogs :

- http://mrhaki.blogspot.ch/search/label/Asciidoc

CheatSheets :

- http://powerman.name/doc/asciidoc

- http://powerman.name/doc/asciidoc-compact.html

Online live editor (alpha) :

- https://asciidoclive.com/

Samples:

- https://github.com/asciidoctor/asciidoctor-maven-examples

2015 © Trivadis

07.03.2015


http://mrhaki.blogspot.ch/search/label/Asciidoc

http://powerman.name/doc/asciidoc

http://powerman.name/doc/asciidoc-compact.html

https://asciidoclive.com/

https://github.com/asciidoctor/asciidoctor-maven-examples

2013 © Trivadis

BASEL BERN BRUGG LAUSANNE ZÜRICH DÜSSELDORF FRANKFURT A.M. FREIBURG I.BR. HAMBURG MÜNCHEN STUTTGART WIEN

2015 © Trivadis

THANK YOU.

Questions?

Ulises Fasoli

Consultant Application Development @ Trivadis

Rue Marterey, 5

CH-1005 Lausanne

[email protected] / [email protected]

http://ufasoli.blogspot.com

@ufasoli

https://github.com/ufasoli/better-doc-with-asciidoc

48 2015 © Trivadis

07.03.2015



Session Feedback – now

Please use your Mobile App to give session feedback

Use "My schedule" if you registered for this session

Otherwise use "Agenda" and the search function

If the mobile App does not work (or if you have

a Windows Phone) use your Mobile Browser

URL: http://lumishow.quickmobile.com/

Event ID: tvdte0115

Username: <your_loginname> (like svv)

Password: <your_loginname><your entry date> (like svv2016)

07/08 March 2015

TechEvent Session Feedback49

http://lumishow.quickmobile.com/

Software

Better documentation with asciidoc and asciidoctor