I gave this presentation at the STC Technical Communication Summit in Dallas (May, 2010).

1. Creating a Wiki-Based Online Help System
C. Rand McKinney
Jeremy Franklin
May 2010

2. Outline
Online help for Second Life Viewer 2.0
Localizable, easy to maintain, context-sensitive
The viewer-help application
Wiki for content management & authoring
Help as web service
Using Mediawiki
Extensions, templates, categories
Content and localization pipeline

3. Caveats
Very new!
Viewer 2.0 released March 31
Defining community processes and policies
Refining
Help content
Localization tools and processes

4. Second Life
Premiere 3D online virtual world
Launched 2003
Large active user "Resident" community
1.4 million users logged in over last 60 days
~80,000 average concurrent users
Desktop client application: Second Life Viewer
Win XP/Vista/7, Mac OS, Linux

5. Second Life Viewer
Client application dates from 2003
Version 1.23
Powerful but complex UI
No help system
Online Knowledge Base
Recently migrated from proprietary system to Second Life Wiki
(Mediawiki)

6. Second Life Viewer 2.0
Complete UI redesign
In development for over a year
Released on 31 Mar 2010
New Features
Integrated Web-Based Media
Easier, Browser-Like Navigation
Side Panel for Frequently-Used Features
Improved Search
Contextual Help

7. Second Life Viewer 2.0

8. Other Help Resources
Welcome Island
In-world new user orientation
Quickstart Guides
Web-based
Linked from sidebar
SL Answers
SL Wiki and Knowledge Base

9. Second Life Wiki
Mediawiki 1.14
8,000+ articles total
Created and maintained by community
~650 articles in official Knowledge Base
Created by Linden Lab
Maintained by community and LL
Custom namespace "Viewerhelp"

10. Second Life Wiki

11. Example wiki article

12. ...Becomes help article

13. Assumptions and requirements
Assumption: Users are online with broadband
Requirements:
Localizable - target: eight languages
Easy to maintain - quarterly releases
Minimize work and expense
Leverage existing knowledge infrastructure

14. Viewer Help system
Viewer (client)
Viewer-help application (server)
Wiki - http://wiki.secondlife.com

15. Viewer Help system - Viewer
Add "?" button to every window, sidebar panel
Pressing F1 equivalent
Clicking "?" sends an HTTP request
Help context ID
Language
Viewer "channel"
Version

16. Viewer Help system - Viewer
Help browser window displays web content
Bare window - Webkit HTML layout engine
UI provided via web application

17. Viewer Help system - server
Scan wiki for changes
Use Mediawiki API to detect changed articles
Every 15 minutes
Request changed articles from wiki
Process and "re-skin" HTML
Save as static files
Respond to HTTP requests from Viewer

18. Viewer Help system - wiki
Use custom Viewerhelp namespace
Set editing rights separately
Easy to isolate queries via API
Key articles:
Active Releases
Map File for each version
Mediawiki API
http://www.mediawiki.org/wiki/API

19. The viewer-help application
Web service
Python
Django web framework
Generator - gets article content from wiki
Router - responds to Viewer HTTP requests
Post-processing

20. Viewer Help architecture

21. The viewer-help generator
Queries wiki using Mediawiki API
15 minute intervals
Gets changes to help articles
Updates viewer-help content
Saves content as static HTML pages
Applies post-processing rules
Improves performance, reliability

22. The viewer-help router
Second Life Viewer issues HTTP GET request
http://viewer-help.secondlife.com/
[LANGUAGE]/
[CHANNEL]/
[VERSION]/
[TOPIC][DEBUG_MODE]
Router returns appropriate article
TOPIC IDs are mapped to wiki articles via map file
CSS "skinning" and add toolbar

23. Active Releases article
Identifies map file for each Viewer channel / version

24. Map file
Maps context IDs to articles
Helps manage and organize content work, localization
Data structure implemented as a wiki table
Viewer-help app reads first two colums
Other columns are informational

25. Map file

26. Active Releases & Map Files

27. Second Life Wiki
Mediawiki 1.14
Acts as content management system
Transclusion enables content reuse
Knowledge Base
Content reuse for UI reference help
Extensions, templates, categories

28. Wiki - Help "skinning"
Help skin
Mediawiki skin
Eliminates much of wiki UI
Application post-processing rules
Strip Viewerhelp namespace, version number
Modify links wiki links to route via the help app.
Add target to external links
Change image source URLs to absolute
CSS applied by router
Look and feel of Viewer UI

29. Wiki Extensions
Per-namespace header / footer
Parser Functions
Facilitates localization
Search and Replace
Useful with localization pipeline
General editing and maintenance
Flagged Revisions
Not used yet by Viewer Help
Enable community contributions, if desired.

30. Wiki Templates
Layout and markup templates
UIref
Tbd, Red
Icon templates
Workflow templates - content pipeline
Only visible in wiki, not help window
Except in debug mode
General templates (from KB)
Note, Warning, Caution, etc.

31. Content Pipeline
Workflow Templates
put articles in categories

32. Content Pipeline

33. Content Pipeline - 2

34. How Localization Works
Redirect from English article to translated article
For each language
English Title /xx English Title in language
xx
Example: "Viewerhelp:People - Friends/de"
#REDIRECT [[Viewerhelp:Leute_-_Freunde]]

35. Localization of Templates
Workflow template sets parser function variable
Other templates detect value
Display appropriate language content based on it

36. Export & Import for Translation
Use Special:Export to export to XML
Load XML into Trados Translation Memory tool
Translate into target languages
Return XML file for each language
Use Special:Import to import XML of each
language translation
Edit wikitext before import
Simple search & replace to set template wikitext

37. Localization Tools & Process
Before importing XML translations
Replace templates in each page
Changes category and sets language variable
In XML files, replace:
{{Help Article Ready for Translation}}
with
{{Translated Help Article|xx|date}}
Import redirects to translated pages
de, fr, ja, etc.
Initial translation only

38. Versioning
Active Releases identifies map file
Map file identifies articles
Article title versioning
No version number is always latest and greatest
Version numbers for older supported versions
Router strips version numbers from display title
Example
Viewerhelp:Preferences - General - latest version
Viewerhelp:Preferences - General/2.0.0

39. Help Content -
Table of Contents
Uses JQuery Treeview plugin
Javascript/CSS
Simple nested bullet lists in wiki
Rendered as expandable / collapsible tree

40. Table of contents

41. Help Content - Glossary
~200 Second Life-specific terms
Most-viewed article
Links from almost every article
Intra-page anchors to each term
Template for easy linking

42. Glossary

43. Help Content - Fallback Article
Displayed when no context ID is active
General entry point
Exception: pre-login help

44. Fallback article

45. Help Content - Search
Google Search Appliance
Results
Language-specific
Version-specific

46. Search

47. Help Content
Task / concept / reference
150+ UI reference topics
High-level Task topics

48. Wiki Access Controls
Main namepace regular articles:
Only logged-in Residents can edit
Knowledge Base:
Logged-in Residents can edit
Edits become default version after revision by Linden or
designated reviewer
Flagged Revision wiki extension
Custom namespaces: Linden Lab Official, Viewerhelp
Only Linden Lab employees can edit
Policy, official product information
Also localized "official" namespace

49. Debug mode
Second Life Viewer admin mode
Used for administration and community management
Also called "god mode"
Access restricted to Linden Lab employees
In debug mode:
See help ID requested by Viewer
See content normally hidden in help (e.g. workflow and editing
templates)
Convenience link to edit help content in wiki

50. Second Life Enterprise
"Behind the firewall" product aimed at
Large enterprise customers
Government and military
Education and academia
Challenge: some installations are offline: NO internet
access
Solution: integrate Viewer-help application with SLE
server
Package static content with application
Links to external resources don't work

51. Open Technical Issues
Detecting changes to transcluded articles
Harder than it looks
Rebuild is workaround
Deleting pages from application
Must automatically detect wiki deletion
Potential memory hog

52. What's Next
Using help content in Knowledge Base articles
Transclusion facilitates single-sourcing
Possibly making Viewerhelp namespace "open" to
user editing
Using Flagged Revisions
Extending scope to other content such as
QuickStart guides

53. Demo
Second Life Viewer 2.0
Context-sensitive help, SL wiki
TOC
Help search
Glossary
Debug/admin mode

54. Q&A
Questions and answers period

55. Thank You!
Reminder:
Please complete Speaker Evaluation