Creating Documentation With A Wiki: The DITA Storm Project

50 %
50 %
Information about Creating Documentation With A Wiki: The DITA Storm Project

Published on October 22, 2007

Author: abelsp

Source: slideshare.net

Description

Presented at DocTrain East 2007 by Alex Karesin -- Wiki-based content authoring is gaining momentum. This simple concept provides exceptional convenience and ease of use for the editors. Ironically, benefits of free-style editing prevent it from penetrating into enterprise environments with stricter content structure and reusability requirements offered by, for example, DITA XML standard. How do you combine convenience of free style writing and advantages of structured, reusable DITA content? The concept of DITA wiki is designed to satisfy both. Alex Karezin shares his experience of creating and adopting DITA content management system that was built by integrating web-based DITA XML editor into wiki and generic CMS.

We will look at wiki platforms from structured authoring perspective; identify suitable candidates, highlight their advantages, review different levels of DITA-wiki integration and summarize efforts required to achieve it. Lastly we will address data migration, survey user experience and draw conclusions.

Creating Documentation With A Wiki: DITA Storm Project Innovative Technology Track

Overview Background Basics: DITA, DITA Storm, Wiki Structure in wiki content DITA – wiki integration Takeaways

Background

Basics: DITA, DITA Storm, Wiki

Structure in wiki content

DITA – wiki integration

Takeaways

DITA Content <topic> <title>Some little topic</title> <body> <p>Here's a <b><i>cute</i></b>, <b>little</b> topic. </p> <ul> <li>Some item</li> <li>Another item</li> </ul> </body> </topic> <task> <title>Restart your system</title> <shortdesc>This is standard procedure after installing any new software.</shortdesc> <taskbody> <steps> <step> <cmd>If you are on a Windows system, go to the start menu.</cmd> </step> <step> <cmd>If you are on a Linux system, contact your system administrator for assistance. You may not need to restart.</cmd> </step> … </steps> </taskbody> </task> <reference> <title>element</title> <shortdesc>Describes a single element …. </shortdesc> <refbody> <refsyn> <codeblock>&lt;!ELEMENT …&gt;</codeblock> </refsyn> <properties> <property> <proptype>string</proptype> <propvalue>name</propvalue> <propdesc>Name of the element… </propdesc> </property> ... </properties> <example> ... </example> </refbody> </reference>

DITA Storm Editor XML Editor Browser-based WYSIWYG DITA-aware …

XML Editor

Browser-based

WYSIWYG

DITA-aware



Wiki wiki + encyclopedia content = wikipedia wiki + dictionary content = wiktictionary wiki + quotations = wikiquote wiki + ??? = wikimania … “A defining characteristic of wiki technology is the ease with which pages can be created and updated”

Wiki Has Some Clear Advantages Easy viewing Easy navigation Easy editing Easy collaboration Versioning Less developed but also available Workflow Authorization Authentication Content reuse … 1.5M articles 2,000 new articles per day 15,000 active editors 206 languages

Easy viewing

Easy navigation

Easy editing

Easy collaboration

Versioning

Less developed but also available

Workflow

Authorization

Authentication

Content reuse



1.5M articles

2,000 new articles per day

15,000 active editors

206 languages

Wiki Features Discussion Versioning Reviewing

Problem: Content Is Unstructured Difficult to edit Difficult to publish Difficult to reuse

Difficult to edit

Difficult to publish

Difficult to reuse

… is it truly unstructured?

More Examples…

Most of Wiki Content Is Structured Topics References Concepts Tasks

Topics

References

Concepts

Tasks

DITA + wiki DITA is asking to be integrated into wiki Adding structure to simplicity

DITA is asking to be integrated into wiki

Adding structure to simplicity

Adding Structure to What’s Out There Basic DITA Integration Easily achievable Deep DITA Integration Difficult Wiki Engines Mediawiki Twiki MoinMoin JotSpot Confluence JSPWiki

Basic DITA Integration

Easily achievable

Deep DITA Integration

Difficult

Wiki Engines

Mediawiki

Twiki

MoinMoin

JotSpot

Confluence

JSPWiki

DITA Storm + wiki

DITA + wiki Excellent fit for: Development documentation Website content management Other applications

Excellent fit for:

Development documentation

Website content management

Other applications

Takeaways DITA is natural Do XML/DITA conversion research now Wiki is especially good for iterative writing Structured wiki authoring in coming

DITA is natural

Do XML/DITA conversion research now

Wiki is especially good for iterative writing

Structured wiki authoring in coming

Add a comment

Related presentations

Related pages

DITA: EServer Technical Communication Library

Articles>Content Management>Documentation>DITA. 5. ... Creating Documentation With A Wiki: The DITA Storm Project. ... DITA is an architecture for creating ...
Read more

Documentation>Wikis: EServer Technical Communication Library

Articles>Documentation>Wikis>Social ... With A Wiki: The DITA Storm Project. ... on a simple calendar project that uses a wiki for documentation.
Read more

DITA at Documentation and Training East Conference | DITA ...

DITA at Documentation and Training East Conference. ... Plan to attend the Documentation ... Creating Documentation With A Wiki: The DITA Storm Project ...
Read more

Storm Documentation

Creating a new Storm project; Documentation. Documentation Index; Manual; Javadoc; FAQ; Getting help. ... Creating a new Storm project; Documentation ...
Read more

Apache Storm

Project Information; Documentation; ... Why use Storm? Apache Storm is a free and open source distributed realtime ... Creating a new Storm project;
Read more

About GitHub Wikis - User Documentation

Every GitHub repository comes equipped with a section for hosting documentation, called a wiki. ... as to what your project can do, wikis can be used to ...
Read more

Home · nathanmarz/storm Wiki · GitHub

Clone this wiki locally. The Storm documentation can now be found on the Storm website. Status; API; Training; Shop; Blog; About; Pricing © 2015 GitHub, Inc.
Read more

Getting started as cheaply as possible | DITA XML.org

setting up your entity resolution catalogs and creating Serna ... the project documentation in subversion and treat ... For a recent DITA project, ...
Read more