Lombardi Wikis A model for collaborative information development (with DITA XML in the mix)

What are Lombardi Wikis? Documentation Wiki and Community Wiki - different use cases, integrated user experience Documentation source in DITA, output to wiki A framework for collaborative information development

Documentation Wiki and Community Wiki - different use cases, integrated user experience

Documentation source in DITA, output to wiki

A framework for collaborative information development

Outline Strategies and tactics System demo Observations Discussion

Strategies and tactics

System demo

Observations

Discussion

Strategies and tactics

Strategies and tactics

Early considerations What is the high-level vision? How should the system work? What processes need to be in place to support the system? What are the key components? Who are the key resources? How to keep stakeholders and collaborators engaged?

What is the high-level vision?

How should the system work?

What processes need to be in place to support the system?

What are the key components?

Who are the key resources?

How to keep stakeholders and collaborators engaged?

Project progression Identify business goals Validate goals with the target users Develop and prioritize use cases Define the product and process requirements Define the resources and milestones Implement and test Go live with pilot audience Implement enhancements and bug fixes Go live Measure and maintain (iterative)

Identify business goals

Validate goals with the target users

Develop and prioritize use cases

Define the product and process requirements

Define the resources and milestones

Implement and test

Go live with pilot audience

Implement enhancements and bug fixes

Go live

Measure and maintain (iterative)

Business goals Help customers and partners scale by providing rich user assistance Make helpful information easier to find – fewer support calls, happier customers Provide a user experience that inspires users to contribute to the community Provide a way for users to network and discuss designs and best practices with experts and users like themselves Increase the productivity of customers, partners, and employees

Help customers and partners scale by providing rich user assistance

Make helpful information easier to find – fewer support calls, happier customers

Provide a user experience that inspires users to contribute to the community

Provide a way for users to network and discuss designs and best practices with experts and users like themselves

Increase the productivity of customers, partners, and employees

Problems to solve Internal pains Customer pains No way to share “non-warranted” knowledge (samples, tips and tricks) with the community No view into “what’s new” Capturing feedback, questions, and discussions about content is difficult Documentation updates not immediately available - tied to product releases Promotion of new and improved content is difficult Lifecycle management issues – stale information is difficult to discover Reviews are time and resource intensive, vulnerable to quality problems Deep knowledge exists in the product ecosystem but is difficult to tap into

Use cases Find out what's new* Search for specific information* Share knowledge* Get notified of updates* Call out nuggets of information (e.g. rate, vote, favorites) Find something to play with Personalize the experience Ask a question Rant and/or rave Report a problem Talk about myself * Identified as highest priority

Find out what's new*

Search for specific information*

Share knowledge*

Get notified of updates*

Call out nuggets of information (e.g. rate, vote, favorites)

Find something to play with

Personalize the experience

Ask a question

Rant and/or rave

Report a problem

Talk about myself

* Identified as highest priority

System demo

System demo

Documentation Wiki

Community Wiki

Space architecture Access point (hub space) Space Deliverable (= ditamap scope)

System architecture DITA XML source in SCMS DITA to Confluence export plugin 100% repeatable publishing routine using Java + XSLT Enterprise Wiki (Confluence) Database (SQL Server 2000) Integrations: LDAP SSO Eclipse RCP and Web applications (dynamic Help content directly from the wiki)

DITA XML source in SCMS

DITA to Confluence export plugin

100% repeatable publishing routine using Java + XSLT

Enterprise Wiki (Confluence)

Database (SQL Server 2000)

Integrations:

LDAP

SSO

Eclipse RCP and Web applications (dynamic Help content directly from the wiki)

Implementation considerations Ditaval and conref Poses major challenges due to unique page ID constraints Best practice: use what the target platform provides where you can – for example, {multi-excerpt}, {include-page} macros that extend the core engine – customize as needed. Navigation Build custom bits to create proper navigation (alphabetical ordering can really corrupt content usability). Add sorting metadata to each page during export, have the engine use the metadata to render a dynamic TOC. Plugin conflicts across versions complicate upgrade scenarios. Plan for upgrade scenarios, especially when customizing plugins. Upgrade scenarios include both server upgrades and individual plugin/macro upgrades.

Ditaval and conref

Poses major challenges due to unique page ID constraints

Best practice: use what the target platform provides where you can – for example, {multi-excerpt}, {include-page} macros that extend the core engine – customize as needed.

Navigation

Build custom bits to create proper navigation (alphabetical ordering can really corrupt content usability). Add sorting metadata to each page during export, have the engine use the metadata to render a dynamic TOC.

Plugin conflicts across versions complicate upgrade scenarios. Plan for upgrade scenarios, especially when customizing plugins. Upgrade scenarios include both server upgrades and individual plugin/macro upgrades.

Conref on the wiki - reusable content

Conref on the wiki – reused content

Observations

Observations

Problems solved After Before Contribute content, link to and from “warranted” content, tag No way to share “non-warranted” knowledge with the community Detailed comparison view with list of recent updates and version rollback No view into “what’s new” Comment, rate, tag, favorite Interactions with the information are cumbersome to conduct Automated and ad-hoc content updates from DITA XML source Documentation updates not immediately available

Road map Major features Milestone Date January 2008 July 2007 March 2007 April 2005 DITA to wiki export (limited) Space architecture for docs and community Hyperlinked TOC pages from ditamaps Alpha Support for ditaval and conref Integrated search across other knowledge portals GA Version 1.5 SSO with other knowledge portals Integrated with product user interface GA Version 1 Dynamic TOCs from ditamaps Beta

DITA to wiki export (limited)

Space architecture for docs and community

Hyperlinked TOC pages from ditamaps

Support for ditaval and conref

Integrated search across other knowledge portals

SSO with other knowledge portals

Integrated with product user interface

Dynamic TOCs from ditamaps

Process Info Dev responds to community updates by manually incorporating revisions into DITA source and then republishing Info Dev replies to the originating comments to acknowledge contributions (and track change) Info Dev helps channel knowledge from other forums to the wiki Info Dev contributes community articles Info Dev maintains UI definitions and system files in source control, where changes can be tracked

Info Dev responds to community updates by manually incorporating revisions into DITA source and then republishing

Info Dev replies to the originating comments to acknowledge contributions (and track change)

Info Dev helps channel knowledge from other forums to the wiki

Info Dev contributes community articles

Info Dev maintains UI definitions and system files in source control, where changes can be tracked

Engagement methods Special content Themed content drives Daily engagement with audience - “tending and mending” Quarterly/opportunistic promo emails to users

Special content

Themed content drives

Daily engagement with audience - “tending and mending”

Quarterly/opportunistic promo emails to users

Collaboration methods Delineation of “warranted” versus “non-warranted” information Brokered collaboration model for “warranted” information assets (Documentation Wiki) Cohesive collaboration model for “non-warranted” information assets (Community Wiki) “Core contributors” versus “trusted contributors” Reference: MIT Sloan Management Review, Fall 2007, Vol. 29: “Breakthroughs and the ‘Long Tail of Innovation’”; L. Fleming

Delineation of “warranted” versus “non-warranted” information

Brokered collaboration model for “warranted” information assets (Documentation Wiki)

Cohesive collaboration model for “non-warranted” information assets (Community Wiki)

“Core contributors” versus “trusted contributors”

Reference: MIT Sloan Management Review, Fall 2007, Vol. 29: “Breakthroughs and the ‘Long Tail of Innovation’”; L. Fleming

Promotion methods Host Webex sessions regularly to increase adoption and get feedback Link to the wiki from Installer (desktop shortcut, last Installer page) Link to the wiki from the product (e.g. Help menu) Wiki pages as dynamic Help Wiki pages as context-sensitive Help Reply to questions on other forums (e.g. discussion groups, email) with links to the wiki Promo emails (to coincide with new features, new and improved content)

Host Webex sessions regularly to increase adoption and get feedback

Link to the wiki from Installer (desktop shortcut, last Installer page)

Link to the wiki from the product (e.g. Help menu)

Wiki pages as dynamic Help

Wiki pages as context-sensitive Help

Reply to questions on other forums (e.g. discussion groups, email) with links to the wiki

Promo emails (to coincide with new features, new and improved content)

Wikipatterns.com Not anti-patterns for us: Empty Pages (use: bubble up the list of empty pages to the home page and ask people to contribute) Registration Required (use: access is restricted to the company user registry - no registration required and no public signup available)

Not anti-patterns for us:

Empty Pages (use: bubble up the list of empty pages to the home page and ask people to contribute)

Registration Required (use: access is restricted to the company user registry - no registration required and no public signup available)

Thank you! Questions? Feedback? [email_address] Blueprint it. The easiest way to get started with BPM is now available! www.lombardi.com/blueprint

Questions? Feedback?

[email_address]