Creating a Wiki-Based Online Help SystemC. Rand McKinney

Jeremy FranklinMay 2010

OutlineOnline help for Second Life Viewer 2.0

Localizable, easy to maintain, context-sensitive

The viewer-help applicationWiki for content management & authoring Help as web service

Using MediawikiExtensions, templates, categories

Content and localization pipeline

Caveats

Very new!

Viewer 2.0 released March 31

Defining community processes and policies

RefiningHelp contentLocalization tools and processes

Second Life

Premiere 3D online virtual worldLaunched 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

Second Life Viewer

Client application dates from 2003Version 1.23

Powerful but complex UI

No help system

Online Knowledge Base Recently migrated from proprietary system to Second Life Wiki (Mediawiki)

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

Second Life Viewer 2.0

Other Help Resources

Welcome IslandIn-world new user orientation

Quickstart Guides Web-basedLinked from sidebar

SL Answers

SL Wiki and Knowledge Base

Second Life Wiki

Mediawiki 1.14

8,000+ articles totalCreated and maintained by community

~650 articles in official Knowledge Base

Created by Linden LabMaintained by community and LL

Custom namespace "Viewerhelp"

Second Life Wiki

Example wiki article

...Becomes help article

Assumptions and requirements

Assumption: Users are online with broadband

Requirements:Localizable - target: eight languages Easy to maintain - quarterly releasesMinimize work and expense

Leverage existing knowledge infrastructure

Viewer Help system

Viewer (client)

Viewer-help application (server)

Wiki - http://wiki.secondlife.com

Viewer Help system - Viewer

Add "?" button to every window, sidebar panelPressing F1 equivalent

Clicking "?" sends an HTTP request

Help context IDLanguageViewer "channel"Version

Viewer Help system - Viewer

Help browser window displays web content

Bare window - Webkit HTML layout engine

UI provided via web application

Viewer Help system - server

Scan wiki for changes

Use Mediawiki API to detect changed articlesEvery 15 minutes

Request changed articles from wiki

Process and "re-skin" HTMLSave as static files

Respond to HTTP requests from Viewer

Viewer Help system - wiki

Use custom Viewerhelp namespaceSet editing rights separatelyEasy to isolate queries via API

Key articles:Active ReleasesMap File for each version

Mediawiki API

http://www.mediawiki.org/wiki/API

The viewer-help application

Web service Python Django web framework

Generator - gets article content from wiki

Router - responds to Viewer HTTP requests

Post-processing

Viewer Help architecture

The viewer-help generator

Queries wiki using Mediawiki API15 minute intervals

Gets changes to help articles Updates viewer-help content

Saves content as static HTML pagesApplies post-processing rulesImproves performance, reliability

The viewer-help router

Second Life Viewer issues HTTP GET requesthttp://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

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 a wiki table Viewer-help app reads first two colums Other columns are informational

Map file

Active Releases & Map Files

Second Life Wiki

Mediawiki 1.14

Acts as content management system

Transclusion enables content reuseKnowledge BaseContent reuse for UI reference help

Extensions, templates, categories

Wiki - Help "skinning"

Help skin Mediawiki skinEliminates much of wiki UI

Application post-processing rules

Strip Viewerhelp namespace, version numberModify 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

Wiki Extensions

Per-namespace header / footer

Parser Functions Facilitates localization

Search and ReplaceUseful with localization pipeline General editing and maintenance

Flagged Revisions

Not used yet by Viewer Help Enable community contributions, if desired.

Wiki Templates

Layout and markup templatesUIrefTbd, RedIcon templates

Workflow templates - content pipelineOnly visible in wiki, not help windowExcept in debug mode

General templates (from KB)Note, Warning, Caution, etc.

Content Pipeline

Workflow Templates put articles in categories

Content Pipeline

Content Pipeline - 2

How Localization Works

Redirect from English article to translated articleFor each language

English Title /xx

Example: "Viewerhelp:People - Friends/de"

#REDIRECT [[Viewerhelp:Leute_-_Freunde]]

English Title in language xx

Localization of Templates

Workflow template sets parser function variable

Other templates detect value

Display appropriate language content based on it

Export & Import for Translation

Use Special:Export to export to XML

Load XML into Trados Translation Memory toolTranslate into target languagesReturn 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

Localization Tools & Process

Before importing XML translationsReplace templates in each pageChanges 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

Versioning

Active Releases identifies map file

Map file identifies articles

Article title versioningNo version number is always latest and greatestVersion numbers for older supported versionsRouter strips version numbers from display title

Example

Viewerhelp:Preferences - General - latest versionViewerhelp:Preferences - General/2.0.0

Help Content - Table of Contents

Uses JQuery Treeview plugin Javascript/CSS

Simple nested bullet lists in wiki

Rendered as expandable / collapsible tree

Table of contents

Help Content - Glossary

~200 Second Life-specific terms

Most-viewed article

Links from almost every articleIntra-page anchors to each termTemplate for easy linking

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 Residents can editEdits become default version after revision by Linden or designated reviewerFlagged Revision wiki extension

Custom namespaces: Linden Lab Official, ViewerhelpOnly Linden Lab employees can editPolicy, official product information

Also localized "official" namespace

Debug mode

Second Life Viewer admin modeUsed for administration and community managementAlso called "god mode"

Access restricted to Linden Lab employees

In debug mode:See help ID requested by ViewerSee content normally hidden in help (e.g. workflow and editing templates)Convenience link to edit help content in wiki

Second Life Enterprise

"Behind the firewall" product aimed atLarge enterprise customersGovernment and militaryEducation and academia

Challenge: some installations are offline: NO internet access

Solution: integrate Viewer-help application with SLE server

Package static content with applicationLinks to external resources don't work

Open Technical Issues

Detecting changes to transcluded articlesHarder than it looks Rebuild is workaround

Deleting pages from application

Must automatically detect wiki deletionPotential memory hog

What's Next

Using help content in Knowledge Base articlesTransclusion facilitates single-sourcing

Possibly making Viewerhelp namespace "open" to user editing

Using Flagged Revisions

Extending scope to other content such as QuickStart guides

DemoSecond Life Viewer 2.0

Context-sensitive help, SL wiki

TOC

Help search

Glossary

Debug/admin mode

Questions and answers periodQ & A

Thank You!

Reminder: Please complete Speaker Evaluation