Growing DITA across the enterprise

IBM User Technologies

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

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

by Don DayArchitect, Lightweight DITA Publishing User Technologies, IBM Corp.


© 2008 IBM CorporationXML-In-Practice 2008 Conference, Arlington VA December 2008

AgendaIntroduction

• 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



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 XTech2005: – 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!

http://idealliance.org/proceedings/xtech05/papers/03-02-04/

http://idealliance.org/proceedings/xtech05/papers/03-02-04/



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

http://ditaworks.raleigh.ibm.com/ index.php?file=//



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 pluginBob 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



Benefits and realizations

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.



Benefits and realizations

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 PatternsThe 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

http://wikipatterns.com/



Lessons learnedTemplates 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 WikiUsers 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 ([email protected]

Growing DITA across the enterprise

Technology

Transcript of Growing DITA across the enterprise