Documentation With Open Source Tools·(ასლი)

856 views
783 views

Published on

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
856
On SlideShare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
6
Comments
0
Likes
0
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>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>

×