Documentation with OpenSource tools

1
Documentation with OpenSource tools

• David Avsajanishvili
• for BarCamp Caspian
• Baku, 2009

mailtoavsd05_at_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
Traditional approach EXAMPLE
5
Traditional approach Disadvantages
6
Traditional approach Disadvantages

• Lack of clear structure

7
Traditional approach Disadvantages

• Lack of clear structure
• WYSIWYG WYG is WYS only!

8
Traditional approach Disadvantages

• Lack of clear structure
• WYSIWYG WYG is WYS only!
• Problems with version-tracking

9
Requirements
10
Requirements

• Structurability

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 Formatselectronic

• HTML / XHTML CSS
• WML
• Derived/related formats HTML Help, Wiki, etc

15
Presentation Formatsprintable

• PDF
• TeX / LaTeX / ConTeXt...
• PostScript, DVI
• XSL-FO

16
Presentation Formatsuniversal

• DOC
• RTF
• OpenDocument

17
(No Transcript)
18
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

19
DocBook Conception
20
DocBook Conception
21
DocBook Example
22
Idea make easily editable Document structure
format
23
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/

24
AsciiDoc Conception
25
ASCIIDOC Example
26
ASCIIDOC Example
27
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.)?

28
AsciiDocSYNTAX
29
AsciiDocSYNTAX
30
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

31
AsciiDoc FEATURESSyntax highlight
32
AsciiDoc FEATURESGRAPHVIZ filter
33
More complex example
34
Advanced DocumentingBatch script

• 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
Advanced DocumentingBatch script
36
Advanced DocumentingAuto-generating content

• Script file

37
Advanced DocumentingAuto-generating content

• Script file
• AsciiDoc source

38
Advanced DocumentingAuto-generating content

• 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