2. DITA Topic Browser: Print-like prev... Your Name Page 2 of 11
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.”
http://localhost/ditawiki-v0.3.12/showmap.php?groupname=One_Year_Retrospective&fil... 9/26/2009 12:28:04 PM
3. DITA Topic Browser: Print-like prev... Your Name Page 3 of 11
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...
http://localhost/ditawiki-v0.3.12/showmap.php?groupname=One_Year_Retrospective&fil... 9/26/2009 12:28:04 PM
4. DITA Topic Browser: Print-like prev... Your Name Page 4 of 11
Layout
Top: Branding/login and overall group/map selection
Left Side: Navigation pane, Search, Tools
Right Side: Reading pane
Bottom: Notices
Views
http://localhost/ditawiki-v0.3.12/showmap.php?groupname=One_Year_Retrospective&fil... 9/26/2009 12:28:04 PM
5. DITA Topic Browser: Print-like prev... Your Name Page 5 of 11
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
http://localhost/ditawiki-v0.3.12/showmap.php?groupname=One_Year_Retrospective&fil... 9/26/2009 12:28:04 PM
6. DITA Topic Browser: Print-like prev... Your Name Page 6 of 11
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.
http://localhost/ditawiki-v0.3.12/showmap.php?groupname=One_Year_Retrospective&fil... 9/26/2009 12:28:04 PM
7. DITA Topic Browser: Print-like prev... Your Name Page 7 of 11
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:
http://localhost/ditawiki-v0.3.12/showmap.php?groupname=One_Year_Retrospective&fil... 9/26/2009 12:28:04 PM
8. DITA Topic Browser: Print-like prev... Your Name Page 8 of 11
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.
http://localhost/ditawiki-v0.3.12/showmap.php?groupname=One_Year_Retrospective&fil... 9/26/2009 12:28:04 PM
9. DITA Topic Browser: Print-like prev... Your Name Page 9 of 11
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:
http://localhost/ditawiki-v0.3.12/showmap.php?groupname=One_Year_Retrospective&fil... 9/26/2009 12:28:04 PM
10. DITA Topic Browser: Print-like prev... Your Name Page 10 of 11
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
http://localhost/ditawiki-v0.3.12/showmap.php?groupname=One_Year_Retrospective&fil... 9/26/2009 12:28:04 PM
11. DITA Topic Browser: Print-like prev... Your Name Page 11 of 11
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...
http://localhost/ditawiki-v0.3.12/showmap.php?groupname=One_Year_Retrospective&fil... 9/26/2009 12:28:04 PM