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.
Documentation with OpenSource tools <ul><ul><li>David Avsajanishvili </li></ul></ul><ul><ul><li>for BarCamp Caspian </li><...
Documentation is… <ul><li>…  the process of building communicable materials (text, tables, diagrams, etc.) to describe som...
Traditional approach: <ul><li>WYSIWYG; </li></ul><ul><li>Using word processing editors; </li></ul><ul><li>Using publishing...
Traditional approach: EXAMPLE
Traditional approach: Disadvantages
Traditional approach: Disadvantages <ul><li>Lack of clear structure </li></ul>
Traditional approach: Disadvantages <ul><li>Lack of clear structure </li></ul><ul><li>WYSIWYG :  WYG  is  WYS  only! </li>...
Traditional approach: Disadvantages <ul><li>Lack of clear structure </li></ul><ul><li>WYSIWYG : WYG is WYS only! </li></ul...
Requirements:
Requirements: <ul><li>Structurability </li></ul>
Requirements: <ul><li>Structurability </li></ul><ul><li>Splitting  content  and  presentation </li></ul>
Requirements: <ul><li>Structurability </li></ul><ul><li>Splitting  structure  and  presentation </li></ul><ul><li>Reusabil...
Requirements: <ul><li>Structurability </li></ul><ul><li>Splitting  content  and  presentation </li></ul><ul><li>Reusabilit...
Presentation Formats: ~electronic~ <ul><li>HTML / XHTML + CSS </li></ul><ul><li>WML </li></ul><ul><li>Derived/related form...
Presentation Formats: ~printable~ <ul><li>PDF </li></ul><ul><li>TeX / LaTeX / ConTeXt... </li></ul><ul><li>PostScript, DVI...
Presentation Formats: ~universal~ <ul><li>DOC </li></ul><ul><li>RTF </li></ul><ul><li>OpenDocument </li></ul>
 
Structure format: DocBook <ul><li>Based on XML/SGML DTD Schema </li></ul><ul><li>Maintained by OASIS  technical  committee...
DocBook: Conception
DocBook: Conception
DocBook: Example
Idea: make easily editable “Document structure” format
Plain-text-based syntax for Documentation – ASCIIDOC <ul><li>Wiki-like plain text syntax </li></ul><ul><li>Fully compatibl...
AsciiDoc: Conception
ASCIIDOC: Example
ASCIIDOC: Example
AsciiDoc SYNTAX <ul><li>Document is started with  Document Header </li></ul><ul><li>Doucment  consists of  Sections,  rang...
AsciiDoc: SYNTAX
AsciiDoc: SYNTAX
AsciiDoc USAGE: <ul><li>Source could be converted to DocBook, HTML, PDF, PostScript ant other formats using command utilit...
AsciiDoc FEATURES: Syntax highlight
AsciiDoc FEATURES: GRAPHVIZ filter
More complex example:
Advanced Documenting: Batch script <ul><li>Prepare source; </li></ul><ul><li>Make script for building documentation from t...
Advanced Documenting: Batch script
Advanced Documenting: Auto-generating content <ul><li>Script file </li></ul>
Advanced Documenting: Auto-generating content <ul><li>Script file </li></ul><ul><li>AsciiDoc source </li></ul>
Advanced Documenting: Auto-generating content <ul><li>Script file </li></ul><ul><li>AsciiDoc source </li></ul><ul><li>Resu...
Other tools <ul><li>MediaWiki, Markdown, reStructuredText, Textile, POD... </li></ul><ul><li>Pandoc </li></ul><ul><li>UMLG...
Resources <ul><li>www.methods.co.nz/asciidoc/  – AsciiDoc </li></ul><ul><li>www.docbook.org  – DocBook </li></ul><ul><li>w...
Upcoming SlideShare
Loading in …5
×

Documentation With Open Source Tools

7,303 views

Published on

Published in: Technology
  • 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 http://kaczanowscy.pl/tomek/2011-09/nice-presentations-in-no-time-with-asciidoc-and-slidy
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

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>mailto:avsd05@gmail.com
  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>http://www.docbook.org </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>http://www.methods.co.nz/asciidoc/ </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>www.methods.co.nz/asciidoc/ – AsciiDoc </li></ul><ul><li>www.docbook.org – DocBook </li></ul><ul><li>www.latex-project.org – LaTeX Project </li></ul><ul><li>www.graphviz.org – Graphviz Project </li></ul><ul><li>johnmacfarlane.net/pandoc/ – Pandoc Project </li></ul><ul><li>www.opendocs.info – Documenting portal </li></ul>

×