Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

IBM DITA Wiki: One Year Retrospective


Published on

Don Day relates lessons learned after a year of operations with the prototype IBM DITA Wiki.

Published in: Technology
  • Be the first to comment

IBM DITA Wiki: One Year Retrospective

  1. 1. 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
  2. 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. 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. 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. 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. 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. 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. 8. DITA Topic Browser: Print-like prev... Your Name Page 8 of 11  Mapalicious demo: Articles that inspired IBM's DITA Wiki The convergence of structure and chaos (Paul Prescod)  (paste into's Wayback Machine) Five Key Differences between Wikipedia & Enterprise Wikis (Stewart Mader)  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. 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)  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)  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)  2. Online Document Collaboration (Eric Armstrong)  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. 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. 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