IBM DITA Wiki: One Year Retrospective

DITA Wiki: One Year Retrospective

Title page Overview

History of the project Design Features

Evolution of the user experience Critiques and validations Lessons learned Benefits Future plans for IBM DITA Wiki Articles that inspired IBM's DITA Wiki Frequently asked questions Demo time

IBM's DITA Wiki: a One Year Retrospective by Don Day, IBM Architect, Lightweight DITA Publishing

User Technologies, IBM Corp.

Presentation for SF Bay Area Arbortext PTC UG

September 23, 2009

© IBM Corporation, 2009

Besides his main work as husband, father, and cat lover, Don designs and supports publishing tools for IBM's Information Development community and beyond. He has represented IBM on the W3C XSL and CSS Working Groups and currently chairs the OASIS DITA Technical Committee. He has B.A.s in English and Journalism and an M.A. in Technical and Professional Communication from New Mexico State University

DITA Topic Browser: Print-like prev... Your Name of 11

9/26/2009 12:28:04 PMhttp://localhost/ditawiki-v0.3.12/showmap.php?groupname=One_Year_Retrospective&fil...

Overview

The IBM DITA Wiki went live as a hosted service within IBM one year ago. Don Day will chronicle the evolution of the user experience, some of the critiques and validations thus far, and the lessons learned that are already informing the next generation of this effort.

History of the project How the project has progressed in the past year since going live on an IBM server:

Up to a year ago

2007: awareness of a web editor that could be the enabler for collaborative work on DITA content. First usability tests.

Early 2008: an internal project was identified as a stakeholder for initial support. Spring 2008: small scale feasibility tests, identification of skills needed April-May 2008: RAD development of initial prototype June 2008: first customer "deliverable" (architecture and features established) August 2008: proposal to provide hosted usage by other groups of this initially dedicated wiki September 2008: initial internal rollout as a hosted service; first additional groups added. December 2008: first public demo, XML-In-Practice Conference. January 2009: first DUG presentation (joint RTP/CTDUG meeting)

In the past year

Creation of project documentation and general wiki documentation Monthly new development of identified core features (security, back end, versioning, locking, interfaces,

etc.) Development of improved dynamic rendering stylesheets Demonstrations to potential stakeholder communities Initial training materials In general, developing all the basic behaviors of a wiki into our existing PHP code base.

Current user characterizations

Some of the current projects and pilots include:

Whitepaper development by a product support team Development of solution Install and Config guides by test teams Software API specification by agile programming teams Support education content development by product SMEs Help development for an internal business tool Engineering manuals (both software and semiconductor LOB cases) Internal workgroup collaboration on policies, standards, and guidelines.

Design “Simple things should be simple, and complex things should be possible.” -- Alan Key

Our premise, which shows on the home page:

“The goal of the IBM DITA Wiki project is to create a 'walk up and use' collaborative authoring environment for professionals who are not necessarily technical writers.”



User and community considerations

Tools exist for users; understanding their needs is the best way to design the right tool.

Usability tests to validate the feasibility of the editor and vendor's interest in fixing identified issues Scenarios to validate that users accepted the proposed wiki workflow for DITA content Active collaboration with developers on our initial stakeholder team to validate our designs and get

precise requirements Validation of general layout (based on popular wiki conventions)

DITA-aware architecture

Overall system architecture: WAMP-like

Windows development platform, initially Apache for the server (common and easy to set up and maintain) SQLite for database services (state info) PHP for fast prototyping (PHP 5 has good DOM and XSL support built in)

DITA-awareness goals:

Load/Save DITA topics from content store Display topic content with on-the-fly content rendering Use a DITA map for navigation (reading mode) Enable conref and other DITA features for live instantiation Enable multiple views of common DITA content Goal of direct interchange of wiki-developed content with any other conforming DITA applications!

Administration choices

Considered a dedicated wiki approach--let each user install their own Hosted service approach had advantages:

Central support of one code set No push update issues Single collection point for reports and support responses Potential for shared collateral

Added admin console to facilitate remote interaction with certain services: fixing lock issues, setting up new accounts, obtaining logs

Content storage

Started with flat space in each group Uploaded content came with folders, so we added hierarchy (fact of life, not easy to deal with, got over

it) Key stakeholder required shared back end, so we added a plugin architecture to isolate further back end

variations from each other, and developed an initial Subversion interface. With early new architecture, we can query and federate search across multiple back ends including DB2

and Filenet.

Features: Overview of essential DITA Wiki features...



Layout

Top: Branding/login and overall group/map selection Left Side: Navigation pane, Search, Tools Right Side: Reading pane

Bottom: Notices

Views



Reading pane is always a "clean view" (no authoring artifacts, but surrounded by the wiki application itself)

Map is always a "navigation view" (ToC-like appearance) A "View As" widget provides multiple pop-over views that apply both to map and to topics:

Clean (rendered without any surrounding UI context) Details (normally hidden content such as prolog or index entries is shown with highlighting) Slides (uses the W3C Slidy stylesheet to render larger font sizes) XML (sends the content out as mime type text/plain)

For a map, "View As" aggregates the content first, then applies the viewing style. In effect, clean view of a map is practically a complete print-like document!

Other features

Dynamic XSLT-based rendering including xref/conref transclusions Import/export as zip Search with future markup semantics as an added filter And of course, standard wiki behaviors and expectations:

File locking for collision avoidance Versioning edit instances, with full-topic revert Logging of events: login, edit, quit, save, etc. Comment facility (stored as DITA for ease of reuse) Admin console for remote setup, config, and so forth.

Evolution of the user experience

Common reactions to new technology: "Fear of the unknown" and "Better the devil you know"

Team leads/coaches as a key interface between myself and the teams: "teach the teachers" transfer of knowledge Single point of interfacing issues to wiki developers Team's trust of "one of their own" asdfasdfasdf

"DITA Cookbook" as a resource on the wiki, developed by the wiki, letting users tell users how to use the system:

About DITA About the Wiki About the DITA editor

This content has been turned into a Bootcamp education session for new writers. Cultivating trust in a new system

Act quickly on reported issues (most are user errors) Put news on the wiki's "home page" (working on notification system)

Critiques and validations thus far

Note that the wiki is often conflated with the editor when users hit an issue, as in: "The wiki didn't take my paste!"

Editor: Some writers found the XML view and camped out there, not bothering to learn the WYSIWYG

interfaces in the editor. The editor was never quite production quality; it was the source of many valid issues such as

losing keystrokes or deleting text in unexpected places. On the other hand, it is a great tool for power users. Those willing to invest in learning it got the



benefits of using it in a word-processor like way. Wiki: generally comfortable--most comments have pertained to desired new features, such as improving

workflow tracking or alternate map views DITA: Some like it, some don't. The main goal for now is to look for ways to reduce multiple operations

into single operations (inserting titled figures with proper id for linking--three insertion steps, 3 intentional content choices, for example)

Identification of familiar and new wiki patterns

Lessons learned that are already informing the next generation of this effort

Balance of features vs ease of use Power users always want more New or lightly committed users want "just the facts"

Best practices for hardware, software choices for a high-reliability application like this Server best practices (hard lesson learned: change motherboard batteries on older hardware now

and then) Data integrity: backup if possible, use redundant RAID configuration, let users know how to

extract their own zips for off-site backup Importance of customizable templates

Most users need custom content that is specific to their project But the group admins should be the main info architects creating those templates. Making the most of embedd structure

Most "New" topics start off as templates But existing topics can be "forked" for new purposes, starting off replete with content Team leads are expected to advise on best practices for each

Benefits

Publishing: ability to use maps and topics directly in DITA Open Toolkit, our internal ID tools, or in any other conforming DITA application

Whitepapers Eclipse information centers Web site content Help files (chm and JavaHelp) RTF for import to other word processors

Via XML's separation of presentation from content, output can be branded easily. The collaborative environment can work for both warranteed and non-entitled content creation and

update, but requires different workflows to ensure quality of warranteed content (typically export into ID process as end game)

User comments I asked a current coach her thoughts about the benefits, best things about, and wishes for the IBM DITA Wiki.

K.

Given that we have few writers and many agile teams, having Dita Wiki makes developing the documentation easier. ID is less of a bottleneck as teams can develop their own docs. It also makes things easier if we are writing the docs as we can have the developers put their thoughts in dita.



Wish list item: Being able to store the topics in CMVC or something similar, instead of having to export the files and then check them into CMVC. We have also had problems with editing topics that have already been checked into CMVC. So if we had a proper database control with the DitaWiki, that would be good.

What a segue to where IBM DITA Wiki is going!

Future plans for IBM DITA Wiki “He who aims at nothing will hit it every time. ” -- Anon

Assumptions

Collaboration happens across multiple domains, infrastructures, and organizational units Content reuse is applicable to more than just authoring scenarios Principles of reuse and collaboration apply to more than just content Content delivery is a non-zero-sum game

Next generation goals

Move from monolithic, one-directional content sharing to widgetized apps, with common content and application services

Develop these services on the best practice RESTful stateless paradigm Reusable widgets enable multiple composite applications using common services (note how helps and

wikis both have left nav and right reading, but have different hosting models) We call this architecture the Dynamic Information Framework, or DIF-- “A toolbox for building DITA

applications. ”

A taste of what's coming...

Interfaces:



Mapalicious demo: https://info2.lotus.com/mapalicious

Articles that inspired IBM's DITA Wiki

The convergence of structure and chaos (Paul Prescod)

http://idealliance.org/proceedings/xtech05/papers/03-02-04/ (paste into archive.org's Wayback Machine)

Five Key Differences between Wikipedia & Enterprise Wikis (Stewart Mader)

http://www.ikiw.org/2009/03/29/5-differences-between-wikipedia-enterprise-wikis/

1. Organization and Access Single workspace vs individual workspaces based on project, department, team, etc., with onfigurable access.

2. Security Login required through firewall; login required to edit (if authorized) Configurable restricted access to spaces

3. Integration LDAP based authentication and roles using intranet ID (same credentials that they use to access email, the company network, etc.)

4. Typical Uses collaboratively building documentation (yes) creating and maintaining knowledge bases (yes) project management (yes) gathering tacit knowledge (knowledge not related to any specific project but essential to getting

things done in an organization) (yes) meeting management, from agenda to minutes and action items. (yes)

Generally, an enterprise wiki will be used in a much wider variety of ways than an Internet wiki, because it is intended to support the wide-ranging needs of the people within an organization. Internet wikis tend to be used primarily for one main application, as is the case with Wikipedia.



5. Contribution Level On an enterprise wiki, the contribution level is much higher based on the fact that people are contributing as part of the daily course of their work, as opposed to voluntarily contributing to a public, Internet wiki.

8 Things You Can Do With an Enterprise Wiki (Stewart Mader)

http://www.ikiw.org/2009/08/21/8-things-you-can-do-with-an-enterprise-wiki/

A very good compendium of wiki design and best practices articles:

Wiki-fying Docs: Is Using Customer-Accessible Wikis for End-User Documentation Gaining Momentum? (Bill Albing)

http://www.keycontent.org/tiki-index.php?page=Wiki-fying+Docs:+Is+Using+Customer-Accessible+Wikis+for+End-User+Documentation+Gaining+Momentum?&redirectpage=Wikis%20and%20Docs

Some informing blog posts by Eric Armstrong (at Sun at the time):

1. Wikis, Docs, and the Reuse Proposition (Eric Armstrong) http://blogs.sun.com/coolstuff/entry/wikis_docs_and_the_reuse

2. Online Document Collaboration (Eric Armstrong) http://blogs.sun.com/coolstuff/entry/online_document_collaboration

Frequently Asked Questions

Does it handle specializations? It is architected to handle standard DITA. However, since the current editor handles only OASIS DITA 1.0-level content models, the content does not currently exploit specialization.

Requested specializations for the wiki include:

Learning & Training Troubleshooting Error Messages IBM's own internal maps and topic types

How do you find content on the company wiki?

Today's search is a Crawl implementation: basic string match within local groups. Walk phase (soon) will add "metadata AND." Run phase (next year) will explore full XPath expressions for highly refined relevance. Stretch goals:

Cross-repository search (enabled by DIF) Other DIF-conforming services (blogs, wikis, etc.) Support folksonomies or controlled value tagging Support comments and ratings

How do you promote it? IBM's DITA Wiki has been promoted through several activities:



Internal demos to candiate user groups, ID workgroups, councils, etc. Internal demos to product and marketing teams Blogging on company blogs and forums Usage metrics are reported monthly up my executive chain; not unexpectedly, this often results in new

connections and potential wiki candidates. Public demos to interested parties

How does IBM's DITA Wiki differ from wikipedia? Wikipedia and other wiki applications built on MediaWiki and other common wikis are usually flat spaces that manage dedicated communities, one community or project per server.

IBM's DITA wiki provides enterprise-level features:

Centralized, hosted service for users across the company Support, via groups, for multiple teams and their unique authorization roles Separate content strategies and workflows within each group See the Stewart Mader references regarding enterprise wiki distinctions!

Besides web editors what other integrations are possible? Editors can be added as plug-ins today. Via the upcoming widget-driven revamping of the architecture, web services may be used to push topics to locally installed desktop editors, for example.

Why no skins or themes? This, and a number of similar minor feature requests, are waiting for a next generation, widgetized implementation upon which we will continue with non-essential build-out. The current focus is on improving robustness and ease of use.

How do you motivate cheerleaders? An interesting question. In conventional wikis, the cultivation of communities is partly a persuasive art. In enterprise wikis, the participants are there to do a job; the wiki is a tool, and they use it. Are they always happy campers? Not always, but they can't walk away individually. So responding to issues that we know about is actually the most important aspect of a "diplomacy-based peacekeeping" that keeps morale going and hopefully wins future projects.

We allow pilot projects for new DITA adopters to explore DITA authoring with low anxiety. Most pilots are expected to evolve into fully committed projects next year.

We also encourage an internal DITA user workgroup to be responsible for finding, cleaning up, and republishing particularly noteworthy items (current focus is on consolidating cheatsheets and style guides, for example).

How do you train users?

Templates: Many teams provide templates that are customized for their particular needs. With much of the structure prepopulated in a template, users usually just "fill in the holes" without too much exposure to underlying structure

Coaches: We learned early on the value of "teaching the teachers" by having a key person be identified as the technical leader for each group. That person gets the initial training, and then is at least a step ahead of the new users coming on board. This has been recognized as a wiki pattern somewhat unique to DITA wikis.

Guides and cheatsheets: How-to topics included within each group's project-oriented maps help users learn the conventions expected by their teams.

Standards for publication: like cheatsheets, these how-to topics keep teams reminded of quality goals



and tips for consistency (how to mark up titled figures, for example).

When will it be available for others? I hear you! IBM's DITA Wiki is still an internal tool, but we are working on the prospects for wider use. Please let the presenter know of your specific interest.

Demo time!

Suggested script:

1. Walk through the real estate 2. Work down through groups 3. At Gutenberg, show alternate maps, acknowledge Kimber 4. At World Time or DMM, show aggregate clean view 5. In World Time, search on "military"; link out from floating nav, save nav as map, reenter that new map.

Questions?

So long, and thanks...



IBM DITA Wiki: One Year Retrospective

Technology

Transcript of IBM DITA Wiki: One Year Retrospective