Documentation With Open Source Tools


Published on

Published in: Technology
1 Comment
  • Personaly, I use Asciidoc and I'm very happy with it. Not only a powerful tool for documentation writing, but also can be used together with slidy to quickly create presentations. See
    Are you sure you want to  Yes  No
    Your message goes here
No Downloads
Total Views
On Slideshare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Documentation With Open Source Tools

  1. 1. Documentation with OpenSource tools <ul><ul><li>David Avsajanishvili </li></ul></ul><ul><ul><li>for BarCamp Caspian </li></ul></ul><ul><ul><li>Baku, 2009 </li></ul></ul>
  2. 2. Documentation is… <ul><li>… the process of building communicable materials (text, tables, diagrams, etc.) to describe some knowledge: </li></ul><ul><li>Scientific and Technical documentation; </li></ul><ul><li>Legal documents, reports, books, articles, etc. </li></ul>
  3. 3. Traditional approach: <ul><li>WYSIWYG; </li></ul><ul><li>Using word processing editors; </li></ul><ul><li>Using publishing systems. </li></ul>
  4. 4. Traditional approach: EXAMPLE
  5. 5. Traditional approach: Disadvantages
  6. 6. Traditional approach: Disadvantages <ul><li>Lack of clear structure </li></ul>
  7. 7. Traditional approach: Disadvantages <ul><li>Lack of clear structure </li></ul><ul><li>WYSIWYG : WYG is WYS only! </li></ul>
  8. 8. Traditional approach: Disadvantages <ul><li>Lack of clear structure </li></ul><ul><li>WYSIWYG : WYG is WYS only! </li></ul><ul><li>Problems with version-tracking </li></ul>
  9. 9. Requirements:
  10. 10. Requirements: <ul><li>Structurability </li></ul>
  11. 11. Requirements: <ul><li>Structurability </li></ul><ul><li>Splitting content and presentation </li></ul>
  12. 12. Requirements: <ul><li>Structurability </li></ul><ul><li>Splitting structure and presentation </li></ul><ul><li>Reusability </li></ul>
  13. 13. Requirements: <ul><li>Structurability </li></ul><ul><li>Splitting content and presentation </li></ul><ul><li>Reusability </li></ul><ul><li>Version tracking possibility </li></ul>
  14. 14. Presentation Formats: ~electronic~ <ul><li>HTML / XHTML + CSS </li></ul><ul><li>WML </li></ul><ul><li>Derived/related formats: HTML Help, Wiki, etc… </li></ul>
  15. 15. Presentation Formats: ~printable~ <ul><li>PDF </li></ul><ul><li>TeX / LaTeX / ConTeXt... </li></ul><ul><li>PostScript, DVI </li></ul><ul><li>XSL-FO </li></ul>
  16. 16. Presentation Formats: ~universal~ <ul><li>DOC </li></ul><ul><li>RTF </li></ul><ul><li>OpenDocument </li></ul>
  17. 18. Structure format: DocBook <ul><li>Based on XML/SGML DTD Schema </li></ul><ul><li>Maintained by OASIS technical committee </li></ul><ul><li>Suitable for defining Books, Articles , Chapters, References, etc. </li></ul><ul><li> </li></ul>
  18. 19. DocBook: Conception
  19. 20. DocBook: Conception
  20. 21. DocBook: Example
  21. 22. Idea: make easily editable “Document structure” format
  22. 23. Plain-text-based syntax for Documentation – ASCIIDOC <ul><li>Wiki-like plain text syntax </li></ul><ul><li>Fully compatible with DocBook </li></ul><ul><li>Could be converted to various Presentation Formats through DocBook </li></ul><ul><li>Could be converted directly to HTML </li></ul><ul><li> </li></ul>
  23. 24. AsciiDoc: Conception
  24. 25. ASCIIDOC: Example
  25. 26. ASCIIDOC: Example
  26. 27. AsciiDoc SYNTAX <ul><li>Document is started with Document Header </li></ul><ul><li>Doucment consists of Sections, ranged by Levels. Sections starts with Section Header (title) ‏ </li></ul><ul><li>Section consists of Paragraphs and Special Blocks (notes, warnings, numbered and labeled lists, tables, etc.) ‏ </li></ul>
  27. 28. AsciiDoc: SYNTAX
  28. 29. AsciiDoc: SYNTAX
  29. 30. AsciiDoc USAGE: <ul><li>Source could be converted to DocBook, HTML, PDF, PostScript ant other formats using command utilities; </li></ul><ul><li>Supports code reusing (composing doc-t from fragments using include:: ) ‏ </li></ul><ul><li>Output could be customized with command-line options and configuration files </li></ul>
  30. 31. AsciiDoc FEATURES: Syntax highlight
  31. 32. AsciiDoc FEATURES: GRAPHVIZ filter
  32. 33. More complex example:
  33. 34. Advanced Documenting: Batch script <ul><li>Prepare source; </li></ul><ul><li>Make script for building documentation from the source; </li></ul><ul><li>Build different format output from single source using the batch; </li></ul><ul><li>Deploy documentation using the batch </li></ul>
  34. 35. Advanced Documenting: Batch script
  35. 36. Advanced Documenting: Auto-generating content <ul><li>Script file </li></ul>
  36. 37. Advanced Documenting: Auto-generating content <ul><li>Script file </li></ul><ul><li>AsciiDoc source </li></ul>
  37. 38. Advanced Documenting: Auto-generating content <ul><li>Script file </li></ul><ul><li>AsciiDoc source </li></ul><ul><li>Result </li></ul>
  38. 39. Other tools <ul><li>MediaWiki, Markdown, reStructuredText, Textile, POD... </li></ul><ul><li>Pandoc </li></ul><ul><li>UMLGraph </li></ul><ul><li>TextUML </li></ul>
  39. 40. Resources <ul><li> – AsciiDoc </li></ul><ul><li> – DocBook </li></ul><ul><li> – LaTeX Project </li></ul><ul><li> – Graphviz Project </li></ul><ul><li> – Pandoc Project </li></ul><ul><li> – Documenting portal </li></ul>