Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Better documentation with asciidoc and asciidoctor

5,069 views

Published on

Documentation if often forsaken by developers for multiple reasons. In this small introduction to AsciiDoc / AsciiDoctor I will attempt to show a better way to write project documentation directly from the IDE using a simple and concise syntax as well as how to integrate it with Maven as to have both the code and the documentation in a single place

Published in: Software

Better documentation with asciidoc and asciidoctor

  1. 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. 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. 3. 2013 © Trivadis2015 © Trivadis Why documentation is important? 3 2015 © Trivadis 07.03.2015 Better documentation with asciidoc and asciidoctor
  4. 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. 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. 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. 7. 2013 © Trivadis2015 © Trivadis Documentation tools 7 2015 © Trivadis 07.03.2015 Better documentation with asciidoc and asciidoctor
  8. 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. 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. 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. 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. 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. 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. 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. 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. 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. 17. 2013 © Trivadis2015 © Trivadis Documentation tools 17 2015 © Trivadis 07.03.2015 Better documentation with asciidoc and asciidoctor
  18. 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. 19. 2013 © Trivadis2015 © Trivadis AsciiDoc 19 2015 © Trivadis 07.03.2015 Better documentation with asciidoc and asciidoctor
  20. 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. 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. 22. 2013 © Trivadis2015 © Trivadis DocBook vs Asciidoc sample 22 2015 © Trivadis 07.03.2015 Better documentation with asciidoc and asciidoctor
  23. 23. 2013 © Trivadis2015 © Trivadis DocBook vs Asciidoc sample…. continued 23 2015 © Trivadis 07.03.2015 Better documentation with asciidoc and asciidoctor
  24. 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. 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. 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. 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. 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. 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. 30. 2013 © Trivadis2015 © Trivadis What can AsciiDoc can do? 30  Links 2015 © Trivadis 07.03.2015 Better documentation with asciidoc and asciidoctor  Checklists
  31. 31. 2013 © Trivadis2015 © Trivadis What can AsciiDoc can do? 31 2015 © Trivadis 07.03.2015 Better documentation with asciidoc and asciidoctor  Images  Videos
  32. 32. 2013 © Trivadis2015 © Trivadis What can AsciiDoc can do? 32 2015 © Trivadis 07.03.2015 Better documentation with asciidoc and asciidoctor  Tables
  33. 33. 2013 © Trivadis2015 © Trivadis What can AsciiDoc can do? 33 2015 © Trivadis 07.03.2015 Better documentation with asciidoc and asciidoctor  Tables (CSV)
  34. 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. 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. 36. 2013 © Trivadis2015 © Trivadis What can AsciiDoc can do? 36  More diagrams! 2015 © Trivadis 07.03.2015 Better documentation with asciidoc and asciidoctor
  37. 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. 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. 39. 2013 © Trivadis2015 © Trivadis AsciiDoctor 39 2015 © Trivadis 07.03.2015 Better documentation with asciidoc and asciidoctor
  40. 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. 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. 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. 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. 44. 2013 © Trivadis2015 © Trivadis AsciiDoctor maven plugin : maven site integration 44 2015 © Trivadis 07.03.2015 Better documentation with asciidoc and asciidoctor
  45. 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. 46. 2013 © Trivadis2015 © Trivadis Tips and useful links 46 2015 © Trivadis 07.03.2015 Better documentation with asciidoc and asciidoctor
  47. 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. 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. 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

×