Page 1
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
Page 2
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
Page 3
2013 © Trivadis2015 © Trivadis
Why documentation is important?
3 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 4
2013 © Trivadis2015 © Trivadis
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
Better documentation with asciidoc and asciidoctor
Page 5
2013 © Trivadis2015 © Trivadis
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
Better documentation with asciidoc and asciidoctor
Page 6
2013 © Trivadis2015 © Trivadis
AGENDA
1. Why documentation is important?
2. Documentation tools
3. AsciiDoc
4. AsciiDoctor
5. Tips and useful links
6 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 7
2013 © Trivadis2015 © Trivadis
Documentation tools
7 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 8
2013 © Trivadis2015 © Trivadis
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
Better documentation with asciidoc and asciidoctor
Page 9
2013 © Trivadis2015 © Trivadis
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
Better documentation with asciidoc and asciidoctor
Page 10
2013 © Trivadis2015 © Trivadis
Plain Text : Disadvantages
10
Too simple
No formatting options
Concurrent edition
No document navigation
2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 11
2013 © Trivadis2015 © Trivadis
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
Better documentation with asciidoc and asciidoctor
Page 12
2013 © Trivadis2015 © Trivadis
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
Better documentation with asciidoc and asciidoctor
Page 13
2013 © Trivadis2015 © Trivadis
Docbook
13 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Extensive set of formatting options
Multiple output formats :
HTML
PDF
Epub
Man pages
…
Customizable output (through CSS)
Page 14
2013 © Trivadis2015 © Trivadis
DocBook: disadvantages
14 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Verbose
Content polluted by tags
Readability issues
“Requires” and editor
Learning curve
“Writing in DocBook is just, inhumane.” Dan Allen
Page 15
2013 © Trivadis2015 © Trivadis
Markdown
15 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Lightweight markup language
Readability
Maturity of the project
Ubiquity
Page 16
2013 © Trivadis2015 © Trivadis
Markdown: disadvantages
16 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
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
Page 17
2013 © Trivadis2015 © Trivadis
Documentation tools
17 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 18
2013 © Trivadis2015 © Trivadis
AGENDA
1. Why documentation is important?
2. Documentation tools
3. AsciiDoc
4. AsciiDoctor
5. Tips and useful links
18 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 19
2013 © Trivadis2015 © Trivadis
AsciiDoc
19 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 20
2013 © Trivadis2015 © Trivadis
AsciiDoc
20 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
“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)
Page 21
2013 © Trivadis2015 © Trivadis
AsciiDoc
21 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
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.
Page 22
2013 © Trivadis2015 © Trivadis
DocBook vs Asciidoc sample
22 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 23
2013 © Trivadis2015 © Trivadis
DocBook vs Asciidoc sample…. continued
23 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 24
2013 © Trivadis2015 © Trivadis
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
Better documentation with asciidoc and asciidoctor
Page 25
2013 © Trivadis2015 © Trivadis
Asciidoc Basic document structure
25 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
HEADER
FOOTER
Section
Section
Section
TOC
Page 26
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
26
Paragraphs
2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Admonitions
Tip
Important
Warning
Caution
Paragraph
Page 27
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
27
Formatted text
Bold
Italic
Monospace
..
2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 28
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
28
Section Titles (headings)
2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 29
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
29
Lists (up to 5 level nesting)
Unordered
Ordered
Labeled
2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Unordered
(with title)
Nested
Ordered
Labeled
Page 30
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
30
Links
2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Checklists
Page 31
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
31 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Images
Videos
Page 32
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
32 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Tables
Page 33
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
33 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Tables (CSV)
Page 34
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
34 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Source code
Coderay
highlightjs
prettify
pygments
Page 35
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
35
Diagrams
Ditaa
Graphviz dot
PlantUML
2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 36
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
36
More diagrams!
2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 37
2013 © Trivadis2015 © Trivadis
What else can AsciiDoc do?
37 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Inclusion
Footnotes
Table of contents
Indexes
Musical notation
Mathematical formulas
Themes
Conditional content
…..
Page 38
2013 © Trivadis2015 © Trivadis
AGENDA
1. Why documentation is important?
2. Documentation tools
3. AsciiDoc
4. AsciiDoctor
5. Tips and useful links
38 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 39
2013 © Trivadis2015 © Trivadis
AsciiDoctor
39 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 40
2013 © Trivadis2015 © Trivadis
AsciiDoctor
40 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
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.
Page 41
2013 © Trivadis2015 © Trivadis
AsciiDoctor maven plugin
41 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Portage of AsciiDoctor to the maven ecosystem
New functionality added regularly
Fast growing community
Page 42
2013 © Trivadis2015 © Trivadis
AsciiDoctor maven plugin (1)
42 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Define the plugin
Plug to a maven phase
Configure some options
Define output (backend)
Page 43
2013 © Trivadis2015 © Trivadis
AsciiDoctor maven plugin (2)
43 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Define a second execution
Define the additional
output format
Define the common
options for both executions
Page 44
2013 © Trivadis2015 © Trivadis
AsciiDoctor maven plugin : maven site integration
44 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 45
2013 © Trivadis2015 © Trivadis
AGENDA
1. Why documentation is important?
2. Documentation tools
3. AsciiDoc
4. AsciiDoctor
5. Tips and useful links
45 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 46
2013 © Trivadis2015 © Trivadis
Tips and useful links
46 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Page 47
2013 © Trivadis2015 © Trivadis
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
Better documentation with asciidoc and asciidoctor
Page 48
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
Better documentation with asciidoc and asciidoctor
Page 49
2013 © Trivadis2015 © Trivadis
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