Creating A Wiki Based Online Help System
Upcoming SlideShare
Loading in...5

Creating A Wiki Based Online Help System



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

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



Total Views
Views on SlideShare
Embed Views



1 Embed 1 1



Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
Post Comment
Edit your comment

    Creating A Wiki Based Online Help System Creating A Wiki Based Online Help System Presentation Transcript

    • Creating a Wiki-Based Online Help System C. Rand McKinney Jeremy Franklin May 2010
    • 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
    • Caveats Very new! Viewer 2.0 released March 31 Defining community processes and policies Refining Help content Localization tools and processes
    • 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
    • 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)
    • 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 Island In-world new user orientation Quickstart Guides Web-based Linked from sidebar SL Answers SL Wiki and Knowledge Base
    • 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"
    • 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 releases Minimize work and expense Leverage existing knowledge infrastructure
    • Viewer Help system Viewer (client) Viewer-help application (server) Wiki -
    • 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
    • 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 articles Every 15 minutes Request changed articles from wiki Process and "re-skin" HTML Save as static files Respond to HTTP requests from Viewer
    • 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
    • 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 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
    • The viewer-help router Second Life Viewer issues HTTP GET request [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 reuse Knowledge Base Content reuse for UI reference help Extensions, templates, categories
    • 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
    • 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.
    • 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.
    • 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 English Title in language xx Example: "Viewerhelp:People - Friends/de" #REDIRECT [[Viewerhelp:Leute_-_Freunde]]
    • 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 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
    • 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
    • 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
    • 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 article Intra-page anchors to each term Template 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 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
    • 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
    • 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
    • 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
    • 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
    • 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