Growing DITA across the enterprise

IBM User Technologies

Growing DITA across the Enterprise: XML
content collaboration for “The Crowd ”

by Don Day
Architect, Lightweight DITA Publishing
User Technologies, IBM Corp.

XML-In-Practice 2008 Conference, Arlington VA December, 2008 © 2008 IBM Corporation


Agenda
Introduction
• Background on DITA and Wikis
• What is DITA, and why?
• What makes DITA unique?
• Then what is a DITA Wiki?
• Role of Enterprise Wikis
• What, then, is the IBM DITA Wiki?
– DITA Wiki “home page”
Project Background
• Conception and socialization of idea
• Project Goals
• Basic architecture
– The taterWiki editor plugin
Live demo
Benefits and realizations
• Value of collaboration
– Community building
• DITA Wiki patterns
• Lessons learned
• Future prospects
Resources

XML-In-Practice 2008 Conference, Arlington VA December 2008 © 2008 IBM Corporation


Background on DITA and Wikis

DITA's topic architecture was designed around the natural
units of content on the web:
– a well-written web page is conceptually a topic;
– a topic may be published to a web page.
Formal suggestion presented by Paul Prescod at XTech
2005:
– Structured Authoring in Wikis: The Convergence of Structure
and Chaos"
Key ideas socialized by Anne Gentle and Eric Armstrong
In all, an idea finally coming to its time!



What is DITA, and why?

XML starter set for technical documentation
– Business appeal for implementation – allows you to start really simple
with XML
– Rich personalization through common metadata enables information
development and delivery targeted to specific customer sets
– Clearly defined extensibility through specialization allows your use to
become complex as you gain experience
– Core tag set based on common HTML tags and rich semantics which
allows users to come up to speed quickly (tested)
Addresses interoperability and sharing of content within and
across corporations with specialization and fallback - allows DITA
to be a platform for collaboration
Open standard backed by IBM and others
Dave Schell, founding corporate sponsor for DITA:
– “DITA is a foundation for collaboration.”



What makes DITA unique?

One of DITA’s main
accomplishments is
providing a consistent
definition of the information
asset to be reused. That
common definition allows
others to take the asset and
use it in their own
deliverables.
DITAmaps provide a
consistent method to
combine and recombine
(reuse) those assets into
meaningful deliverables.



What makes DITA unique?

Darwin: DITA utilizes principles
of inheritance for specialization
similar to OO programming
Information Typing: DITA was
designed for technical
information based on information
architecture types of Concept,
Task and Reference
Architecture: DITA is based on
XML and supports extending
design and processes through
inheritance and specialization



Then what is a DITA Wiki?

Using a Wiki paradigm to provide a cohesive collection of
core Web services:
– DITA content authoring
– collaboration community environment (with a familiar Wiki feel)
– Dynamic content rendering and navigation
An application comprised of a set of services
– Features unique to Wikis
– Features uniquely related to support of DITA
– Common core services (server framework, back end,
interfaces, etc.)



Role of Enterprise wikis

I think there are fundamental reasons why there is a demand
or market for what are called “Enterprise wikis. ”
Encourage deep contribution of knowledge as collateral
across the company
Enable collaboration for teams whose members are widely
separated geographically
Good for readers too: a wiki is as much a reading platform
as an authoring platform
Wide accessibility of this collected information across the
enterprise.



What, then, is the IBM DITA Wiki?

The IBM DITA Wiki was developed to be a lightweight, web-based DITA
authoring environment designed for non-ID professionals.
Examples of audience and use:
– Members of a development team collaborating on topics that will eventually appear
in a product’s information center.
– Those same members collaborating on team-related documents (schedules, plans,
designs, records).
– Members of an integration test team collaborating on the installation guide for a
multi-product solution.
– Members of a workgroup collaborating on policies, standards, and guidelines for
their organization.
– "Bloggers" who thrive on messaging about new collaborative technologies!
Current DITA Wiki components:
– The DITA Workspace: Work with DITA projects; work with maps and topics; publish
content; more…
– The DITA Storm editor: A web-based DITA editor from Inmedius that is launched
from the DITA Workspace



DITA Wiki
“home page”



Project background: Conception and socialization of idea
We have Wikis, we have DITA, we have people who are behind the idea? What does it take
to make it happen?
Assess current technologies:
– Wikis based on wikitext have a tight relationship between the markup and the function of the site
– Not clear that DITA as a format can be natively inserted without compromises to the document
architecture
– One practical option: import DITA in and out of current Wikis
• No impact to fundamental wiki engine
• But no clear integration of DITA features into that engine; interaction is "at a distance"
• Quality of the content can be incrementally improved, not clear what the ceiling of function is.
Proposed approach:
– Keeping the core virtues of DITA in mind, attempt to build the authoring/viewing platform around
the document architecture
– Select one or more candidate web editors for the authoring aspect
– Support as much of DITA's value proposition as well as possible
– But keep all the interfaces easy, familiar, low-barrier for new users who are not trained as writers
Process of winning backing for development:
– Usability pilot on a basic framework
– Engage a supportive end-user team to provide requirements, feedback
– Demo, Demo, Demo!



Project goals

Unify content plugin API and expectations
– Share IBM DITA Wiki content with other collaborative services
Enable output services for users
– Make use of the ubiquitous DITA Open Toolkit
– Remote server based to manage performance of the Wiki itself
Enable packaging for:
– Download to user's system
– Sending to translation vendor
– Sharing content with OEM



Basic architecture

PHP application framework (easy, agile for the prototype
programmers)
Layout based on popular Wiki/Web conventions (left nav and
tools, right reading)
Plugin architecture to enable better modularity, independent
testing of new modules, easier unit test, etc..
LDAP-based login to support corporate and license admin
concerns
Separate user groups, hosted on central server
Briefcase mode allows unplugging and working away from
the cloud



The taterWiki editor plugin
Bob Flavin, IBM Research, who has demonstrated an editor component in the
DITA Wiki:
– IBM has hosted several editors successfully on this platform. taterWiki is IBM's
internal technology. The plugin interface allows clean separation and choice of
appropriate tools for future goals. Bob Flavin, architect for taterWiki, provided these
comments about the editor:
– Documents used to be flat -- office documents today are just strings or letters, the
software has very little concept of the relationships between parts of the document.
– By representing the documents as heirarchical, semi-structured, semantically-
tagged, formatting-free objects, aka DITA. The computer can start to assist us in
searching the contents of the document and making them more useful.
– taterWiki is a tool that allows these DITA documents to be shared and edited
collaboratively in real-time or asynchronously, with fine-grained control over who can
change what and what side effects these changes can have.
– By maintaining the documents in an 'abstract' format -- free of the formating
information that HTML, word and PDF documents are -- taterWiki can 'render' the
documents in different manners depending on user's needs, preferences and
privileges.
– For example, you could be looking at a car repair manual for a 2005 Mustang with a
6 cylinder engine as a mechanic while I'm looking at, and annotating the same
document in a view appropriate an owner of a convertible, 2006 Mustang with the 4
cylinder engine. Some parts of the manual will appear the same to both of us, some
will be customed for our interests. Our ability to change or annotate the document
depend on our roles and privileges.



Live demo

We will look at several demo content types and a
sample interaction session.
– Specifications
– Collaborative "books"
– Help sets
– How to documentation




Value of collaboration
– content collaboration,
– information harvesting/authoring
Community building
– Users of shared collaboration sites are implicitly part of
whatever community roosts there. Care and feeding of
the customer is never as important as when rolling out a
new service! We learned some things about how to
improve relationships all around.




A sense of trust has a healthy infectious effect on users who
come into the program with skeptical attitudes.
– Don't overpromise on capabilities of the tool.
– Be responsive and show leadership in dealing with whatever
issues the new user has.
Provide a support forum and community through which
users and seekers can connect with each other and have a
healthy dialog about change.
– IBM has a DITA Advocates internal workgroup that provided
both Q&A and presentation oriented telecons every month.
Very active members of this group also help out with reviewing
site content and mentoring new users of the DITA authoring
tools in use across IBM.



DITA Wiki Patterns
The popular web site, wikipatterns.com, is a resource for ways to construct
(or avoid) particular content or behaviors on a wiki site. You might think of
a pattern as a convention, good or bad, that people can follow to achieve
particular ends in a wiki.
While standard wiki patterns (or anti-patterns) might apply in the DITA Wiki,
the nature of having structured information in an enterprise environment
necessarily invents new ways of looking at some behaviors or techniques.
We've spotted these uniquely-DITA patterns so far on the site:
People Patterns
– DITA Guru
(like the traditional Champion pattern but with skill in helping with DITA)
People Anti-patterns
– Fear of Breaking Something
Adoption Patterns
– DITA Linking
– Templates and forks
– Create new map from dir/query listings
Adoption Anti-patterns
– Access policies



Lessons learned
Templates rock!
– Authors like having structure to start from
– Template boilerplate ensures at least a starting consistency in
an environment that would otherwise be anarchic
– Any current topic is basically a template for some new use:
"save as" = "fork" = "start with fairly ready-to-go existing
boilerplate"
Documentation Projects are not the only paradigm for using
a Wiki
Users need to be continually reminded to think outside their
preconceptions
Battle of the bulge (keeping the experience light in the
presence of demand for more function)
For viability, visibility counts!



Future prospects

The IBM DITA Wiki began as a rapid prototype that quickly
proved its value and is on its way to becoming a dependable
tool. Some of the clear things still to explore include:
– Finish off remaining Wiki feature enablement.
– Extend the plugin interfaces to make all aspects of the
application "hot swappable" insofar as we can: new output
transforms, alternate editors, alternate group UI schemes,
choice of back end from file system to code versioning system
to full CMS, and so forth.
– Utilize web services to enable other tools to use our content or
capabilities as policies allow.
– Review the code for modularity and clean function.
– Encourage a plugin building community to expand the tool to
do amazing new things with DITA as content!



Thanks!

Any questions?

Contact: Don Day (dond@us.ibm.com


Growing DITA across the enterprise

More Related Content

What's hot

Viewers also liked

Similar to Growing DITA across the enterprise

Recently uploaded

Growing DITA across the enterprise