• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
Documentation With Open Source Tools
 

Documentation With Open Source Tools

on

  • 8,369 views

 

Statistics

Views

Total Views
8,369
Views on SlideShare
8,201
Embed Views
168

Actions

Likes
4
Downloads
62
Comments
1

8 Embeds 168

http://www.barcampcaspian.org 106
http://www.slideshare.net 20
http://www.bax.az 17
http://opendocs.info 9
http://www.opendocs.info 7
http://docs.avsd.webfactional.com 4
http://web.archive.org 4
http://wayback.archive.org 1
More...

Accessibility

Categories

Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel

11 of 1 previous next

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
  • Personaly, I use Asciidoc and I'm very happy with it. Not only a powerful tool for documentation writing, but also can be used together with slidy to quickly create presentations. See http://kaczanowscy.pl/tomek/2011-09/nice-presentations-in-no-time-with-asciidoc-and-slidy
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    Documentation With Open Source Tools Documentation With Open Source Tools Presentation Transcript

    • Documentation with OpenSource tools
        • David Avsajanishvili
        • for BarCamp Caspian
        • Baku, 2009
      mailto:avsd05@gmail.com
    • 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.
    • Traditional approach: EXAMPLE
    • 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
      • 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
    • Advanced Documenting: Batch script
    • Advanced Documenting: Auto-generating content
      • Script file
    • Advanced Documenting: Auto-generating content
      • Script file
      • AsciiDoc source
    • Advanced Documenting: Auto-generating content
      • Script file
      • AsciiDoc source
      • 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