Embed Size (px)
Citation preview
Documentation with OpenSource tools
David Avsajanishvilifor BarCamp CaspianBaku, 2009
mailto:[email protected]
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.
Traditional approach:
WYSIWYG; Using word
processing editors; Using publishing
systems.
Tra
ditio
na
l ap
pro
ac
h: E
XA
MP
LE
Traditional approach: Disadvantages
Traditional approach: Disadvantages Lack of clear
structure
Traditional approach: Disadvantages Lack of clear
structure WYSIWYG:
WYG is WYS only!
Traditional approach: Disadvantages Lack of clear
structure WYSIWYG:
WYG is WYS only!
Problems with version-tracking
Requirements:
Requirements:
Structurability
Requirements:
Structurability Splitting content
and presentation
Requirements:
Structurability Splitting structure
and presentation Reusability
Requirements:
Structurability Splitting content
and presentation Reusability Version tracking
possibility
Presentation Formats:~electronic~ HTML / XHTML + CSS WML Derived/related formats:
HTML Help, Wiki, etc…
Presentation Formats:~printable~ PDF TeX / LaTeX / ConTeXt... PostScript, DVI XSL-FO
Presentation Formats:~universal~ DOC RTF OpenDocument
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
DocBook: Conception
DocBook: Conception
DocBook: Example
Idea: make easily editable “Document
structure” format
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/
AsciiDoc: Conception
ASCIIDOC: Example
ASCIIDOC: Example
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.)
AsciiDoc:SYNTAX
AsciiDoc:SYNTAX
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
AsciiDoc FEATURES:Syntax highlight
AsciiDoc FEATURES:GRAPHVIZ filter
More complex example:
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
Advanced Documenting:Batch script
Advanced Documenting:Auto-generating content1.Script file
Advanced Documenting:Auto-generating content1.Script file
2.AsciiDoc source
Advanced Documenting:Auto-generating content1.Script file
2.AsciiDoc source
3.Result
Other tools
MediaWiki, Markdown, reStructuredText, Textile, POD...
Pandoc UMLGraph TextUML
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
