IBM DITA Wiki: One Year Retrospective

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

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

User Technologies, IBM Corp.

Presentation for SF Bay Area Arbortext PTC UG

September 23, 2009
© IBM Corporation, 2009

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


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

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (19)

Similaire à IBM DITA Wiki: One Year Retrospective

Similaire à IBM DITA Wiki: One Year Retrospective (20)

Plus de Don Day

Plus de Don Day (6)

Dernier

Dernier (20)

IBM DITA Wiki: One Year Retrospective