Creating Documentation With A Wiki: The DITA Storm Project

transcript

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

<topic> <title>Some little topic</title> <body> Here's a cute, little topic. <ul> <li>Some item</li> <li>Another item</li> </ul> </body></topic>

DITA Content

<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><!ELEMENT …></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• …

wiki + encyclopedia content = wikipediawiki + dictionary content = wiktictionarywiki + quotations = wikiquotewiki + ??? = 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

Wiki Features

Discussion

Versioning

Reviewing

Problem: Content Is Unstructured• 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

DITA + wiki

• 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

DITA Storm + wiki

DITA + wiki

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

Creating Documentation With A Wiki: The DITA Storm Project

Business