dynamic_toc_sequoyah.pngAnne Gentle writes about a presentation on a customer and documentation wiki sourced with DITA topics by Lisa Dyer of Lombardi Software at the February Central Texas DITA User Group meeting. Lisa’s presentation explores how the company is using DITA and a wiki as the framework for collaborative information development, both internally and with customers who have a support login.

First, what’s DITA?

It stands for Darwin Information Typing Architecture, and, “is an XML-based architecture for authoring, producing, and delivering technical information.” (Source: Wikipedia)
DITA was originally developed by IBM and encourages content to be created & organized by topics, then published in multiple formats like HTML, PDF, and online help formats used by Java-based projects, and companies like Microsoft and Oracle.

Lisa’s Presentation

On the importance of starting with internal use only at first:

Lisa Dyer recommends a pilot wiki, internal only at first, to ferret problems out while building in time to fix the problems. Michele Guthrie from Cisco… also has found that internal-only wikis helped them understand the best practices for wiki documentation.

That way, when you open the wiki to the external community, the internal contributors from your organization are well-versed in wiki use and ready to help nurture the external community’s growth. That last thing you want is the internal people just getting used to the wiki at the same time as the external folk.
On choosing an open source or enterprise wiki:

Lisa said to ask questions while evaluating, such as where do you want the intellectual property to develop? Will you pay for support? Who are your key resources internally, and do you need to supplement resources with external help?
They found it faster to get up and running and supported with an enterprise engine and chose Confluence, but she also noted that you “vote” for updates and enhancements with dollars rather than, say, community influence. (Editorial note – I’m opining on whether you get updates to open source wiki engines through community influence.)

Anne’s editorial note makes a good point. For Confluence, we have a public JIRA instance where anyone can raise an issue and others can vote on it – which helps the development team get direct feedback on what customers need. This is a good example of combining voting with dollars (when you buy a new software license or continuing maintenance) and community influence.
Lisa’s talk also looks at topics like Getting DITA to talk to the wiki, creating a wiki table of contents from a DITA map, and some of the limitations and considerations to think about when starting a project like this.

Fresh ideas, announcements, and inspiration for your team, delivered weekly.

Subscribe now