better documentation with asciidoc and asciidoctor
TRANSCRIPT
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
2013 © Trivadis2015 © Trivadis
Why documentation is important?
3 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
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
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
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
2013 © Trivadis2015 © Trivadis
Documentation tools
7 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
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
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
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
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
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
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
Epub
Man pages
…
Customizable output (through CSS)
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
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
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
2013 © Trivadis2015 © Trivadis
Documentation tools
17 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
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
2013 © Trivadis2015 © Trivadis
AsciiDoc
19 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
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)
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.
2013 © Trivadis2015 © Trivadis
DocBook vs Asciidoc sample
22 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
2013 © Trivadis2015 © Trivadis
DocBook vs Asciidoc sample…. continued
23 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
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
ePub
…
2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
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
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
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
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
28
Section Titles (headings)
2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
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
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
30
Links
2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Checklists
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
31 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Images
Videos
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
32 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Tables
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
33 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
Tables (CSV)
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
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
2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
36
More diagrams!
2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
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
…..
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
2013 © Trivadis2015 © Trivadis
AsciiDoctor
39 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
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
…
Written in Ruby but ported to the JVM (JRuby)
Out of the box with a complete set of templates, styles, etc.
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
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)
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
2013 © Trivadis2015 © Trivadis
AsciiDoctor maven plugin : maven site integration
44 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
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
2013 © Trivadis2015 © Trivadis
Tips and useful links
46 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
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
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
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