Downloaded 148 times
Uploaded byRashad Aliyev
Documentation With Open Source Tools
The document discusses various tools for technical documentation, including traditional word processing editors, DocBook, AsciiDoc, LaTeX, and others. It highlights some disadvantages of traditional approaches like lack of structure and version tracking. Formats like DocBook, AsciiDoc, LaTeX allow splitting content from presentation, reusability, and version tracking. AsciiDoc is a plain text syntax that can be converted to DocBook and other formats like HTML and PDF.
More Related Content
Similar to Documentation With Open Source Tools
Documentation With Open Source Tools
- 1. Documentation with OpenSourcetools David Avsajanishvili for BarCamp Caspian Baku, 2009 mailto:avsd05@gmail.com
- 2. Documentation is… … the process of building communicable materials (text, tables, diagrams, etc.) to describe some knowledge: Scientific and Technical documentation; Legal documents, reports, books, articles, etc.
- 3. Traditional approach: WYSIWYG;Using word processing editors; Using publishing systems.
- 4.
- 5.
- 6. Traditional approach: DisadvantagesLack of clear structure
- 7. Traditional approach: DisadvantagesLack of clear structure WYSIWYG : WYG is WYS only!
- 8. Traditional approach: DisadvantagesLack of clear structure WYSIWYG : WYG is WYS only! Problems with version-tracking
- 9.
- 10.
- 11. Requirements: Structurability Splitting content and presentation
- 12. Requirements: Structurability Splitting structure and presentation Reusability
- 13. Requirements: Structurability Splitting content and presentation Reusability Version tracking possibility
- 14. Presentation Formats: ~electronic~HTML / XHTML + CSS WML Derived/related formats: HTML Help, Wiki, etc…
- 15. Presentation Formats: ~printable~PDF TeX / LaTeX / ConTeXt... PostScript, DVI XSL-FO
- 16. Presentation Formats: ~universal~DOC RTF OpenDocument
- 17.
- 18. Structure format: DocBookBased on XML/SGML DTD Schema Maintained by OASIS technical committee Suitable for defining Books, Articles , Chapters, References, etc. http://www.docbook.org
- 19.
- 20.
- 21.
- 22. Idea: make easilyeditable “Document structure” format
- 23. Plain-text-based syntax forDocumentation – ASCIIDOC Wiki-like plain text syntax Fully compatible with DocBook Could be converted to various Presentation Formats through DocBook Could be converted directly to HTML http://www.methods.co.nz/asciidoc/
- 24.
- 25.
- 26.
- 27. AsciiDoc SYNTAX Documentis started with Document Header Doucment consists of Sections, ranged by Levels. Sections starts with Section Header (title) Section consists of Paragraphs and Special Blocks (notes, warnings, numbered and labeled lists, tables, etc.)
- 28.
- 29.
- 30. AsciiDoc USAGE: Sourcecould be converted to DocBook, HTML, PDF, PostScript ant other formats using command utilities; Supports code reusing (composing doc-t from fragments using include:: ) Output could be customized with command-line options and configuration files
- 31. AsciiDoc FEATURES: Syntaxhighlight
- 32.
- 33.
- 34. Advanced Documenting: Batchscript Prepare source; Make script for building documentation from the source; Build different format output from single source using the batch; Deploy documentation using the batch
- 35.
- 36. Advanced Documenting: Auto-generatingcontent Script file
- 37. Advanced Documenting: Auto-generatingcontent Script file AsciiDoc source
- 38. Advanced Documenting: Auto-generatingcontent Script file AsciiDoc source Result
- 39. Other tools MediaWiki,Markdown, reStructuredText, Textile, POD... Pandoc UMLGraph TextUML
- 40. Resources www.methods.co.nz/asciidoc/ – AsciiDoc www.docbook.org – DocBook www.latex-project.org – LaTeX Project www.graphviz.org – Graphviz Project johnmacfarlane.net/pandoc/ – Pandoc Project www.opendocs.info – Documenting portal