DITA + Wiki = The Open-Source DITA2Wiki Project
By Lisa Dyer |
|
In early 2005, the Information Development group at Lombardi Software, Inc. set out to implement a single-system solution for three business problems; Lombardi's user community had a lot of knowledge to share but didn't have a forum to do so; there was no facility to deliver and discover updates to the product documentation in between releases; and, there was no efficient feedback loop that could help drive improvements into the product.
Importantly, Lombardi had implemented DITA earlier and was reaping significant benefits from its implementations. Abandoning DITA for, for example, content sourced on a wiki, was not considered a reasonable option.
After considering many systems and tools on the market, and deciding that none was powerful enough, Lombardi Software developed a framework of tools and processes that now powers their mission-critical knowledge system called the Lombardi Wikis. In 2007, Lombardi donated this framework to the community as the open-source "DITA2Wiki Project" on SourceForge.net.
The DITA2Wiki Framework
At a high level, the DITA2Wiki framework consists of two components:
- Business process
- Tooling
The Business Process
The DITA2Wiki framework implements two repeatable business processes. One process handles company-generated content (referred to as "warrantied" content), and one for community-generated content (referred to as "non-warrantied" content).
When community members want to find help with a particular task or feature, they can search all content types or filter search results based on specific conditions. The documentation and community content can be interlinked and labeled to aid information discovery.
- Brokered = single individual is the hub through which others interact.
- Cohesive = people develop separate and independent relationships with one another that do not include a central individual.
- Core contributor = required to contribute, tied to performance goals.
- Trusted = not required but actively engaged and well-motivated to contribute e.g. field and support personnel, partners.
Process for company-generated content:
- Information developer writes new content in DITA XML.
- Content is imported to the documentation wiki and injected into the existing navigation structure using the DITA2wiki import tool.
- Community member comments page(s) to correct or complement the content. Updates are immediately available to all.
- Information developer receives update notifications from the target wiki, incorporates them to the DITA XML source, and then updates all outputs, including the wiki.
Process for community-generated content:
- Community member writes new content on the community wiki. Content is immediately available to all.
- Information developer harvests the content and incorporates the appropriate scope into the DITA XML source for all outputs. Content on the community wiki is marked as harvested.
- Information developer publishes updates to the documentation wiki using the DITA2wiki import tool.
- Optionally, information developer adds additional links and tags across content spaces to help people discover the available updates.
Tooling
The tooling consists of the following components:
- A wiki engine that lends itself to structured information and provides configurable security schemas (for example, Confluence or TWiki)
- DITA maps and topics
- DITA2Wiki import tool (a DITA2Wiki Project distribution)
To get started on implementing the DITA2Wiki framework, download and install an evaluation version of the target wiki, and the open-source DITA2Wiki binary distribution and its open-source prerequisites. Visit the DITA2Wiki Project wiki for complete instructions (see section REFERENCES).
Can I Use the DITA2Wiki Framework with Any Wiki?
The DITA2Wiki Project distributions currently support the Confluence Enterprise wiki (because of legacy reasons; Lombardi Software uses Confluence). But the implementation can be customized to support other wikis, and this is a goal of the open-source DITA2Wiki Project.
The primary areas to customize are:
- XSL that transforms DITA XML to wikitext markup.
- Communication layer between the tool and the wiki in order to import the transformed content. DITA2Wiki implements SOAP to communicate with a Java-based wiki. The RCP/XML protocol supports non-Java wikis.
