documentation with open source tools
TRANSCRIPT
![Page 1: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/1.jpg)
Documentation with OpenSource tools
David Avsajanishvilifor BarCamp CaspianBaku, 2009
mailto:[email protected]
![Page 2: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/2.jpg)
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.
![Page 3: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/3.jpg)
Traditional approach:
WYSIWYG; Using word
processing editors; Using publishing
systems.
![Page 4: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/4.jpg)
Tra
ditio
na
l ap
pro
ac
h: E
XA
MP
LE
![Page 5: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/5.jpg)
Traditional approach: Disadvantages
![Page 6: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/6.jpg)
Traditional approach: Disadvantages Lack of clear
structure
![Page 7: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/7.jpg)
Traditional approach: Disadvantages Lack of clear
structure WYSIWYG:
WYG is WYS only!
![Page 8: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/8.jpg)
Traditional approach: Disadvantages Lack of clear
structure WYSIWYG:
WYG is WYS only!
Problems with version-tracking
![Page 9: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/9.jpg)
Requirements:
![Page 10: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/10.jpg)
Requirements:
Structurability
![Page 11: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/11.jpg)
Requirements:
Structurability Splitting content
and presentation
![Page 12: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/12.jpg)
Requirements:
Structurability Splitting structure
and presentation Reusability
![Page 13: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/13.jpg)
Requirements:
Structurability Splitting content
and presentation Reusability Version tracking
possibility
![Page 14: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/14.jpg)
Presentation Formats:~electronic~ HTML / XHTML + CSS WML Derived/related formats:
HTML Help, Wiki, etc…
![Page 15: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/15.jpg)
Presentation Formats:~printable~ PDF TeX / LaTeX / ConTeXt... PostScript, DVI XSL-FO
![Page 16: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/16.jpg)
Presentation Formats:~universal~ DOC RTF OpenDocument
![Page 17: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/17.jpg)
![Page 18: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/18.jpg)
Structure format: DocBook
Based on XML/SGML DTD Schema Maintained by OASIS technical committee Suitable for defining Books, Articles,
Chapters, References, etc. http://www.docbook.org
![Page 19: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/19.jpg)
DocBook: Conception
![Page 20: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/20.jpg)
DocBook: Conception
![Page 21: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/21.jpg)
DocBook: Example
![Page 22: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/22.jpg)
Idea: make easily editable “Document
structure” format
![Page 23: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/23.jpg)
Plain-text-based syntax for Documentation – 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/
![Page 24: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/24.jpg)
AsciiDoc: Conception
![Page 25: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/25.jpg)
ASCIIDOC: Example
![Page 26: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/26.jpg)
ASCIIDOC: Example
![Page 27: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/27.jpg)
AsciiDoc SYNTAX
Document is 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.)
![Page 28: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/28.jpg)
AsciiDoc:SYNTAX
![Page 29: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/29.jpg)
AsciiDoc:SYNTAX
![Page 30: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/30.jpg)
AsciiDoc USAGE:
Source could 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
![Page 31: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/31.jpg)
AsciiDoc FEATURES:Syntax highlight
![Page 32: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/32.jpg)
AsciiDoc FEATURES:GRAPHVIZ filter
![Page 33: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/33.jpg)
More complex example:
![Page 34: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/34.jpg)
Advanced Documenting:Batch script
1.Prepare source;
2.Make script for building documentation from the source;
3.Build different format output from single source using the batch;
4.Deploy documentation using the batch
![Page 35: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/35.jpg)
Advanced Documenting:Batch script
![Page 36: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/36.jpg)
Advanced Documenting:Auto-generating content1.Script file
![Page 37: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/37.jpg)
Advanced Documenting:Auto-generating content1.Script file
2.AsciiDoc source
![Page 38: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/38.jpg)
Advanced Documenting:Auto-generating content1.Script file
2.AsciiDoc source
3.Result
![Page 39: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/39.jpg)
Other tools
MediaWiki, Markdown, reStructuredText, Textile, POD...
Pandoc UMLGraph TextUML
![Page 40: Documentation With Open Source Tools](https://reader035.vdocuments.us/reader035/viewer/2022062300/5549b348b4c905e5048b475c/html5/thumbnails/40.jpg)
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