Creating a Wiki-Based Online Help System
             C. Rand McKinney
              Jeremy Franklin
                 May ...
Outline
Online help for Second Life Viewer 2.0
   Localizable, easy to maintain, context-sensitive

The viewer-help applic...
Caveats
Very new!

Viewer 2.0 released March 31

Defining community processes and policies

Refining
  Help content
  Loca...
Second Life
Premiere 3D online virtual world
   Launched 2003

Large active user "Resident" community
   1.4 million users...
Second Life Viewer
Client application dates from 2003
   Version 1.23

Powerful but complex UI

No help system

Online Kno...
Second Life Viewer 2.0
Complete UI redesign

In development for over a year
   Released on 31 Mar 2010

New Features
   In...
Second Life Viewer 2.0
Other Help Resources
Welcome Island
  In-world new user orientation

Quickstart Guides
  Web-based
  Linked from sidebar

...
Second Life Wiki
Mediawiki 1.14

8,000+ articles total
  Created and maintained by community

~650 articles in official Kn...
Second Life Wiki
Example wiki article
...Becomes help article
Assumptions and requirements

Assumption: Users are online with broadband

Requirements:
   Localizable - target: eight la...
Viewer Help system


Viewer (client)

Viewer-help application (server)

Wiki - http://wiki.secondlife.com
Viewer Help system - Viewer
Add "?" button to every window, sidebar panel
   Pressing F1 equivalent

Clicking "?" sends an...
Viewer Help system - Viewer
Help browser window displays web content

Bare window - Webkit HTML layout engine

UI provided...
Viewer Help system - server
Scan wiki for changes

Use Mediawiki API to detect changed articles
   Every 15 minutes

Reque...
Viewer Help system - wiki
Use custom Viewerhelp namespace
   Set editing rights separately
   Easy to isolate queries via ...
The viewer-help application
Web service
   Python
   Django web framework

Generator - gets article content from wiki

Rou...
Viewer Help architecture
The viewer-help generator
Queries wiki using Mediawiki API
   15 minute intervals

Gets changes to help articles
   Update...
The viewer-help router
Second Life Viewer issues HTTP GET request
      http://viewer-help.secondlife.com/
        [LANGUA...
Active Releases article
Identifies map file for each Viewer channel / version
Map file
Maps context IDs to articles

Helps manage and organize content work, localization

Data structure implemented as...
Map file
Active Releases & Map Files
Second Life Wiki

Mediawiki 1.14

Acts as content management system

Transclusion enables content reuse
   Knowledge Base
...
Wiki - Help "skinning"
Help skin
   Mediawiki skin
   Eliminates much of wiki UI

Application post-processing rules
   Str...
Wiki Extensions
Per-namespace header / footer

Parser Functions
  Facilitates localization

Search and Replace
  Useful wi...
Wiki Templates
Layout and markup templates
   UIref
   Tbd, Red
   Icon templates

Workflow templates - content pipeline
 ...
Content Pipeline

  Workflow Templates
  put articles in categories
Content Pipeline
Content Pipeline - 2
How Localization Works
Redirect from English article to translated article
  For each language

English Title /xx         ...
Localization of Templates
Workflow template sets parser function variable

Other templates detect value

Display appropria...
Export & Import for Translation
Use Special:Export to export to XML

Load XML into Trados Translation Memory tool
  Transl...
Localization Tools & Process

 Before importing XML translations
    Replace templates in each page
    Changes category a...
Versioning
Active Releases identifies map file

Map file identifies articles

Article title versioning
   No version numbe...
Help Content -
            Table of Contents

Uses JQuery Treeview plugin
   Javascript/CSS

Simple nested bullet lists in...
Table of contents
Help Content - Glossary
~200 Second Life-specific terms

Most-viewed article

Links from almost every article
   Intra-pag...
Glossary
Help Content - Fallback Article

Displayed when no context ID is active

General entry point

Exception: pre-login help
Fallback article
Help Content - Search

Google Search Appliance

Results
  Language-specific
  Version-specific
Search
Help Content
Task / concept / reference

150+ UI reference topics

High-level Task topics
Wiki Access Controls
Main namepace regular articles:
   Only logged-in Residents can edit

Knowledge Base:
   Logged-in Re...
Debug mode
Second Life Viewer admin mode
  Used for administration and community management
  Also called "god mode"

Acce...
Second Life Enterprise
"Behind the firewall" product aimed at
   Large enterprise customers
   Government and military
   ...
Open Technical Issues


Detecting changes to transcluded articles
   Harder than it looks
   Rebuild is workaround

Deleti...
What's Next

Using help content in Knowledge Base articles
  Transclusion facilitates single-sourcing

Possibly making Vie...
Demo
Second Life Viewer 2.0

Context-sensitive help, SL wiki

TOC

Help search

Glossary

Debug/admin mode
Q&A
Questions and answers period
Thank You!

Reminder:
Please complete Speaker Evaluation
Upcoming SlideShare
Loading in …5
×

Creating A Wiki Based Online Help System

4,267 views

Published on

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

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
4,267
On SlideShare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
24
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Creating A Wiki Based Online Help System

  1. 1. Creating a Wiki-Based Online Help System C. Rand McKinney Jeremy Franklin May 2010
  2. 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. 3. Caveats Very new! Viewer 2.0 released March 31 Defining community processes and policies Refining Help content Localization tools and processes
  4. 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. 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. 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. 7. Second Life Viewer 2.0
  8. 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. 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. 10. Second Life Wiki
  11. 11. Example wiki article
  12. 12. ...Becomes help article
  13. 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. 14. Viewer Help system Viewer (client) Viewer-help application (server) Wiki - http://wiki.secondlife.com
  15. 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. 16. Viewer Help system - Viewer Help browser window displays web content Bare window - Webkit HTML layout engine UI provided via web application
  17. 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. 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. 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. 20. Viewer Help architecture
  21. 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. 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. 23. Active Releases article Identifies map file for each Viewer channel / version
  24. 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. 25. Map file
  26. 26. Active Releases & Map Files
  27. 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. 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. 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. 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. 31. Content Pipeline Workflow Templates put articles in categories
  32. 32. Content Pipeline
  33. 33. Content Pipeline - 2
  34. 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. 35. Localization of Templates Workflow template sets parser function variable Other templates detect value Display appropriate language content based on it
  36. 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. 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. 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. 39. Help Content - Table of Contents Uses JQuery Treeview plugin Javascript/CSS Simple nested bullet lists in wiki Rendered as expandable / collapsible tree
  40. 40. Table of contents
  41. 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. 42. Glossary
  43. 43. Help Content - Fallback Article Displayed when no context ID is active General entry point Exception: pre-login help
  44. 44. Fallback article
  45. 45. Help Content - Search Google Search Appliance Results Language-specific Version-specific
  46. 46. Search
  47. 47. Help Content Task / concept / reference 150+ UI reference topics High-level Task topics
  48. 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. 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. 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. 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. 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. 53. Demo Second Life Viewer 2.0 Context-sensitive help, SL wiki TOC Help search Glossary Debug/admin mode
  54. 54. Q&A Questions and answers period
  55. 55. Thank You! Reminder: Please complete Speaker Evaluation

×