This document discusses better documentation tools using AsciiDoc and AsciiDoctor. It begins by explaining why documentation is important for keeping track of applications, improving quality, and easing knowledge transfer. Common documentation tools are outlined, including plain text, word processors, DocBook, Markdown, and AsciiDoc. The features and advantages of AsciiDoc are described, including its readable syntax and ability to produce various output formats. AsciiDoctor is introduced as a processor that converts AsciiDoc content to HTML, DocBook, EPUB and PDF. Tips for using AsciiDoc such as separating content into files and using conditional blocks are also provided.

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.2015
Better documentation with asciidoc and asciidoctor
1

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

3. 2013 © Trivadis2015 © Trivadis
Why documentation is important?
3 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor

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

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

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

7. 2013 © Trivadis2015 © Trivadis
Documentation tools
7 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor

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

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

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

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

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

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)

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

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

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

17. 2013 © Trivadis2015 © Trivadis
Documentation tools
17 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor

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

19. 2013 © Trivadis2015 © Trivadis
AsciiDoc
19 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor

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)

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.

22. 2013 © Trivadis2015 © Trivadis
DocBook vs Asciidoc sample
22 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor

23. 2013 © Trivadis2015 © Trivadis
DocBook vs Asciidoc sample…. continued
23 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor

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

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

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

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

28. 2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
28
 Section Titles (headings)
2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor

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

30. 2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
30
 Links
2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
 Checklists

31. 2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
31 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
 Images
 Videos

32. 2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
32 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
 Tables

33. 2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
33 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor
 Tables (CSV)

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

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

36. 2013 © Trivadis2015 © Trivadis
What can AsciiDoc can do?
36
 More diagrams!
2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor

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

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

39. 2013 © Trivadis2015 © Trivadis
AsciiDoctor
39 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor

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.

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

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)

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

44. 2013 © Trivadis2015 © Trivadis
AsciiDoctor maven plugin : maven site integration
44 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor

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

46. 2013 © Trivadis2015 © Trivadis
Tips and useful links
46 2015 © Trivadis
07.03.2015
Better documentation with asciidoc and asciidoctor

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

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
ulises.fasoli@trivadis.com / ufasoli@gmail.com
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

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 Feedback
49