Creating a Wiki-Based  Online Help System C. Rand McKinney March 2011
Outline <ul><ul><li>Second Life and Viewer 2 </li></ul></ul><ul><ul><ul><li>Context-sensitive help system </li></ul></ul><...
<ul><ul><li>  Large active user &quot;Resident&quot; community </li></ul></ul><ul><ul><ul><li>750,000 active Residents (Q3...
<ul><ul><li>Client application </li></ul></ul><ul><ul><ul><li>Windows XP/Vista/7, Mac OS, Linux </li></ul></ul></ul><ul><u...
Viewer Help system <ul><ul><li>Goals: </li></ul></ul><ul><ul><ul><li>Provide context-sensitive help system </li></ul></ul>...
Viewer Help system
Viewer Help system  - Viewer <ul><ul><li>Every window, panel  </li></ul></ul><ul><ul><ul><li>Help button </li></ul></ul></...
Viewer Help system - Viewer  <ul><li>Sends an HTTP request </li></ul><ul><ul><li>Help context ID </li></ul></ul><ul><ul><l...
Viewer Help system - Viewer
Example wiki article
...Becomes help article
Viewer Help system - application <ul><ul><li>Scans wiki for changes </li></ul></ul><ul><ul><li>  Detects changed articles ...
The Viewer Help application <ul><ul><li>Web service (REST) </li></ul></ul><ul><ul><ul><li>Python  </li></ul></ul></ul><ul>...
Viewer Help architecture
Viewer Help generator <ul><ul><li>Queries wiki using Mediawiki API </li></ul></ul><ul><ul><ul><li>15 minute intervals  </l...
Viewer Help router <ul><ul><li>Second Life Viewer issues HTTP GET request </li></ul></ul><ul><ul><ul><ul><li>http://viewer...
Viewer Help router <ul><ul><li>Router returns appropriate article </li></ul></ul><ul><ul><ul><li>Active Releases  table id...
Active Releases table <ul><ul><li>Identifies map file for each Viewer channel / version </li></ul></ul>
Map file <ul><ul><li>Maps context IDs to articles </li></ul></ul><ul><ul><li>Helps manage and organize content work, local...
Map file
Active Releases & Map Files
Versioning <ul><ul><li>Article title convention </li></ul></ul><ul><ul><ul><li>No version number - &quot;latest and greate...
Viewer Help system - Wiki <ul><ul><li>Acts as content management system </li></ul></ul><ul><ul><li>Help skin </li></ul></u...
Second Life Wiki
Second Life Wiki  <ul><ul><li>Mediawiki 1.15 </li></ul></ul><ul><ul><li>Custom &quot;Viewerhelp&quot; namespace </li></ul>...
Wiki Access Controls <ul><ul><li>Main namepace regular articles </li></ul></ul><ul><ul><ul><li>Logged-in Residents can fre...
Wiki Extensions <ul><ul><li>Per-namespace header / footer  </li></ul></ul><ul><ul><li>Parser Functions  </li></ul></ul><ul...
Wiki Templates <ul><ul><li>Layout and markup templates </li></ul></ul><ul><ul><li>Workflow templates - content pipeline </...
Content Pipeline Categories <ul><ul><li>Workflow templates  put articles in categories </li></ul></ul>
How Localization Works <ul><ul><li>Redirect from English article to translated article </li></ul></ul><ul><ul><ul><li>For ...
Export & Import for Translation <ul><ul><li>Use  Special:Export  to export to XML </li></ul></ul><ul><ul><li>Load XML into...
Help Content <ul><ul><li>General content </li></ul></ul><ul><ul><ul><li>Task / concept / reference </li></ul></ul></ul><ul...
  Table of Contents <ul><ul><li>Simple nested bullet lists in wiki </li></ul></ul><ul><ul><li>JQuery Treeview plugin  </li...
  Table of Contents
Table of contents
  Summary: Pros and Cons  <ul><li>Pros </li></ul><ul><ul><li>Easy to support multiple simultaneous releases </li></ul></ul...
Questions and answers period Thank You! <ul><ul><li>Second Life: http://www.secondlife.com </li></ul></ul><ul><ul><li>Seco...
Upcoming SlideShare
Loading in...5
×

Creating a Wiki-Based Online Help System (Abridged)

4,291

Published on

Presentation given at the 2011 Writers UA conference in Long Beach, CA.
http://www.writersua.com/

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

  • Be the first to like this

No Downloads
Views
Total Views
4,291
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
0
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Creating a Wiki-Based Online Help System (Abridged)

  1. 1. Creating a Wiki-Based Online Help System C. Rand McKinney March 2011
  2. 2. Outline <ul><ul><li>Second Life and Viewer 2 </li></ul></ul><ul><ul><ul><li>Context-sensitive help system </li></ul></ul></ul><ul><ul><li>The Viewer Help system </li></ul></ul><ul><ul><ul><li>Viewer / App / Wiki </li></ul></ul></ul><ul><ul><ul><li>Custom help window in Viewer </li></ul></ul></ul><ul><ul><ul><li>Viewer Help web service </li></ul></ul></ul><ul><ul><ul><li>Mediawiki for content management, authoring </li></ul></ul></ul><ul><ul><li>Using Mediawiki </li></ul></ul><ul><ul><ul><li>Namespaces, extensions, templates, categories  </li></ul></ul></ul><ul><li>  </li></ul><ul><ul><li>Help content and localization </li></ul></ul>
  3. 3. <ul><ul><li>  Large active user &quot;Resident&quot; community </li></ul></ul><ul><ul><ul><li>750,000 active Residents (Q3 2010)  </li></ul></ul></ul><ul><ul><ul><li>~80,000 average concurrent users  </li></ul></ul></ul><ul><li>  </li></ul><ul><li>  </li></ul><ul><ul><li>Leading 3D online virtual world </li></ul></ul><ul><ul><ul><li>Immersive 3D environment </li></ul></ul></ul><ul><ul><ul><li>User-created content </li></ul></ul></ul>
  4. 4. <ul><ul><li>Client application </li></ul></ul><ul><ul><ul><li>Windows XP/Vista/7, Mac OS, Linux </li></ul></ul></ul><ul><ul><li>Powerful but complex UI </li></ul></ul><ul><ul><ul><li>UI completely redesigned  </li></ul></ul></ul><ul><ul><ul><li>Released in early 2010   </li></ul></ul></ul>Second Life Viewer 2
  5. 5. Viewer Help system <ul><ul><li>Goals: </li></ul></ul><ul><ul><ul><li>Provide context-sensitive help system </li></ul></ul></ul><ul><ul><ul><li>Leverage Second Life Wiki </li></ul></ul></ul><ul><li>  </li></ul><ul><ul><li>Assumption:  </li></ul></ul><ul><ul><ul><li>Users are online with broadband </li></ul></ul></ul><ul><ul><li>Requirements: </li></ul></ul><ul><ul><ul><li>Localizable - target: eight languages </li></ul></ul></ul><ul><ul><ul><li>Easy to maintain - quarterly releases </li></ul></ul></ul><ul><ul><ul><li>Minimize development work and expense </li></ul></ul></ul><ul><ul><li>Small team  </li></ul></ul>
  6. 6. Viewer Help system
  7. 7. Viewer Help system - Viewer <ul><ul><li>Every window, panel  </li></ul></ul><ul><ul><ul><li>Help button </li></ul></ul></ul><ul><ul><ul><li>Unique context ID </li></ul></ul></ul><ul><ul><li>Help window </li></ul></ul><ul><ul><ul><li>Use existing embedded Webkit browser </li></ul></ul></ul>
  8. 8. Viewer Help system - Viewer <ul><li>Sends an HTTP request </li></ul><ul><ul><li>Help context ID </li></ul></ul><ul><ul><li>Language </li></ul></ul><ul><ul><li>Viewer &quot;channel&quot; </li></ul></ul><ul><ul><li>Version </li></ul></ul>
  9. 9. Viewer Help system - Viewer
  10. 10. Example wiki article
  11. 11. ...Becomes help article
  12. 12. Viewer Help system - application <ul><ul><li>Scans wiki for changes </li></ul></ul><ul><ul><li>  Detects changed articles </li></ul></ul><ul><ul><ul><li>Use Mediawiki API </li></ul></ul></ul><ul><ul><ul><li>Query every 15 minutes </li></ul></ul></ul><ul><li>  </li></ul><ul><ul><li>Requests changed articles from wiki </li></ul></ul><ul><ul><ul><li>Process and &quot;re-skin&quot; HTML </li></ul></ul></ul><ul><ul><ul><li>Save as static files </li></ul></ul></ul><ul><li>  </li></ul><ul><ul><li>Responds to HTTP requests from Viewer </li></ul></ul>
  13. 13. The Viewer Help application <ul><ul><li>Web service (REST) </li></ul></ul><ul><ul><ul><li>Python </li></ul></ul></ul><ul><ul><ul><li>Django web framework </li></ul></ul></ul><ul><li>  </li></ul><ul><ul><li>Generator  </li></ul></ul><ul><ul><ul><li>Scrapes content from wiki </li></ul></ul></ul><ul><ul><ul><li>Saves as static files </li></ul></ul></ul><ul><ul><li>Router  </li></ul></ul><ul><ul><ul><li>Responds to Viewer HTTP requests </li></ul></ul></ul><ul><ul><ul><li>Adds UI, skinning </li></ul></ul></ul>
  14. 14. Viewer Help architecture
  15. 15. Viewer Help generator <ul><ul><li>Queries wiki using Mediawiki API </li></ul></ul><ul><ul><ul><li>15 minute intervals </li></ul></ul></ul><ul><ul><li>Gets changes to help articles  </li></ul></ul><ul><ul><ul><li>Updates viewer-help content </li></ul></ul></ul><ul><ul><li>Saves content as static HTML pages </li></ul></ul><ul><ul><ul><li>Applies post-processing rules </li></ul></ul></ul><ul><ul><ul><li>Improves performance, reliability </li></ul></ul></ul>
  16. 16. Viewer Help router <ul><ul><li>Second Life Viewer issues HTTP GET request </li></ul></ul><ul><ul><ul><ul><li>http://viewer-help.secondlife.com/  </li></ul></ul></ul></ul><ul><ul><ul><ul><li>  [LANGUAGE]/ </li></ul></ul></ul></ul><ul><ul><ul><ul><li>  [CHANNEL]/ </li></ul></ul></ul></ul><ul><ul><ul><ul><li>  [VERSION]/ </li></ul></ul></ul></ul><ul><ul><ul><ul><li>  [TOPIC][DEBUG_MODE] </li></ul></ul></ul></ul><ul><ul><li>Router returns appropriate article </li></ul></ul><ul><li>  </li></ul><ul><ul><li>TOPIC IDs are mapped to wiki articles via map file  </li></ul></ul><ul><li>  </li></ul><ul><ul><li>CSS &quot;skinning&quot; and add toolbar </li></ul></ul><ul><li>  </li></ul>
  17. 17. Viewer Help router <ul><ul><li>Router returns appropriate article </li></ul></ul><ul><ul><ul><li>Active Releases table identifies map file for a given release </li></ul></ul></ul><ul><ul><ul><li>Map file identifies wiki article for a given topic ID </li></ul></ul></ul><ul><ul><li>Application post-processing rules </li></ul></ul><ul><ul><ul><li>Strip Viewerhelp namespace, version number </li></ul></ul></ul><ul><ul><ul><li>Modify links wiki links to route via the help app. </li></ul></ul></ul><ul><ul><li>CSS &quot;skinning&quot; and add UI </li></ul></ul><ul><li>  </li></ul>
  18. 18. Active Releases table <ul><ul><li>Identifies map file for each Viewer channel / version </li></ul></ul>
  19. 19. Map file <ul><ul><li>Maps context IDs to articles </li></ul></ul><ul><ul><li>Helps manage and organize content work, localization </li></ul></ul><ul><li>  </li></ul><ul><ul><li>Data structure implemented as a wiki table </li></ul></ul><ul><ul><ul><li>Viewer-help app reads first two colums </li></ul></ul></ul><ul><ul><ul><li>Other columns are informational </li></ul></ul></ul><ul><li>  </li></ul>
  20. 20. Map file
  21. 21. Active Releases & Map Files
  22. 22. Versioning <ul><ul><li>Article title convention </li></ul></ul><ul><ul><ul><li>No version number - &quot;latest and greatest&quot; </li></ul></ul></ul><ul><ul><ul><li>Version numbers for older supported versions </li></ul></ul></ul><ul><ul><ul><li>Router strips version numbers from display title </li></ul></ul></ul><ul><li>  </li></ul><ul><ul><li>Example </li></ul></ul><ul><ul><ul><li>Viewerhelp:Preferences - General - latest version (e.g 2.1) </li></ul></ul></ul><ul><ul><ul><li>Viewerhelp:Preferences - General/2.0.0  - older version </li></ul></ul></ul><ul><li>  </li></ul>
  23. 23. Viewer Help system - Wiki <ul><ul><li>Acts as content management system </li></ul></ul><ul><ul><li>Help skin </li></ul></ul><ul><ul><ul><li>Eliminates much of wiki UI </li></ul></ul></ul><ul><ul><li>Namespaces - access control </li></ul></ul><ul><ul><li>Mediawiki extensions </li></ul></ul><ul><ul><li>Templates and categories </li></ul></ul>
  24. 24. Second Life Wiki
  25. 25. Second Life Wiki <ul><ul><li>Mediawiki 1.15 </li></ul></ul><ul><ul><li>Custom &quot;Viewerhelp&quot; namespace </li></ul></ul><ul><ul><ul><li>Set editing rights separately </li></ul></ul></ul><ul><ul><ul><li>Easy to isolate queries via API </li></ul></ul></ul><ul><ul><li>Key articles: </li></ul></ul><ul><ul><ul><li>Active Releases </li></ul></ul></ul><ul><ul><ul><li>Map File for each version </li></ul></ul></ul><ul><li>  </li></ul><ul><ul><li>Mediawiki API </li></ul></ul><ul><ul><ul><li>http://www.mediawiki.org/wiki/API </li></ul></ul></ul>
  26. 26. Wiki Access Controls <ul><ul><li>Main namepace regular articles </li></ul></ul><ul><ul><ul><li>Logged-in Residents can freely edit </li></ul></ul></ul><ul><ul><li>Knowledge Base articles </li></ul></ul><ul><ul><ul><li>Logged-in Residents can edit </li></ul></ul></ul><ul><ul><ul><li>Content under revision control via Flagged Revisions </li></ul></ul></ul><ul><ul><ul><li>Linden Lab employee or designee must approve </li></ul></ul></ul><ul><ul><li>Custom namespaces: Linden Lab Official, Viewerhelp </li></ul></ul><ul><ul><ul><li>Only Linden Lab employees can edit </li></ul></ul></ul><ul><ul><ul><li>Policy, official product information </li></ul></ul></ul><ul><li>  </li></ul>
  27. 27. Wiki Extensions <ul><ul><li>Per-namespace header / footer </li></ul></ul><ul><ul><li>Parser Functions  </li></ul></ul><ul><ul><ul><li>Facilitates localization </li></ul></ul></ul><ul><ul><li>Search and Replace </li></ul></ul><ul><ul><ul><li>Useful with localization pipeline </li></ul></ul></ul><ul><ul><ul><li>General editing and maintenance </li></ul></ul></ul><ul><li>  </li></ul><ul><ul><li>Flagged Revisions   </li></ul></ul><ul><ul><ul><li>Enable community contributions, if desired. </li></ul></ul></ul><ul><ul><ul><li>Not used yet by Viewer Help </li></ul></ul></ul>
  28. 28. Wiki Templates <ul><ul><li>Layout and markup templates </li></ul></ul><ul><ul><li>Workflow templates - content pipeline </li></ul></ul><ul><ul><ul><li>Only visible in wiki, not in Viewer   (except debug mode) </li></ul></ul></ul><ul><ul><ul><li>Add articles to workflow categories </li></ul></ul></ul>
  29. 29. Content Pipeline Categories <ul><ul><li>Workflow templates put articles in categories </li></ul></ul>
  30. 30. How Localization Works <ul><ul><li>Redirect from English article to translated article </li></ul></ul><ul><ul><ul><li>For each language </li></ul></ul></ul><ul><ul><li>English Title /xx </li></ul></ul><ul><li>  </li></ul><ul><ul><li>Example &quot;Viewerhelp:People - Friends/de&quot;   Redirects to &quot;Viewerhelp:Leute - Freunde&quot; </li></ul></ul>English Title in language xx
  31. 31. Export & Import for Translation <ul><ul><li>Use Special:Export to export to XML </li></ul></ul><ul><ul><li>Load XML into Trados Translation Memory tool </li></ul></ul><ul><ul><ul><li>Translate into target languages </li></ul></ul></ul><ul><ul><ul><li>Return XML file for each language </li></ul></ul></ul><ul><ul><li>Use Special:Impor t to import XML of each language translation </li></ul></ul><ul><ul><ul><li>Edit wikitext before import </li></ul></ul></ul><ul><ul><ul><li>Simple search & replace to set template wikitext </li></ul></ul></ul>
  32. 32. Help Content <ul><ul><li>General content </li></ul></ul><ul><ul><ul><li>Task / concept / reference </li></ul></ul></ul><ul><ul><ul><li>150+ UI reference topics </li></ul></ul></ul><ul><ul><li>Special articles </li></ul></ul><ul><ul><ul><li>Table of Contents </li></ul></ul></ul><ul><ul><ul><li>Fallback (default) article  </li></ul></ul></ul><ul><li>  </li></ul><ul><ul><li>Search uses Google Search Appliance  </li></ul></ul><ul><ul><ul><li>Language-specific results </li></ul></ul></ul><ul><ul><ul><li>Version-specific results </li></ul></ul></ul>
  33. 33.   Table of Contents <ul><ul><li>Simple nested bullet lists in wiki </li></ul></ul><ul><ul><li>JQuery Treeview plugin  </li></ul></ul><ul><ul><ul><li>Javascript/CSS </li></ul></ul></ul><ul><li>  </li></ul><ul><ul><li>In Viewer renders as expandable / collapsible tree </li></ul></ul>
  34. 34.   Table of Contents
  35. 35. Table of contents
  36. 36.   Summary: Pros and Cons  <ul><li>Pros </li></ul><ul><ul><li>Easy to support multiple simultaneous releases </li></ul></ul><ul><ul><li>Decent, popular authoring environment </li></ul></ul><ul><ul><li>Can leverage community contributions </li></ul></ul><ul><ul><li>Good for distributed team </li></ul></ul><ul><ul><li>Mediawiki extensibility </li></ul></ul><ul><ul><li>Built on open source software </li></ul></ul><ul><li>Cons </li></ul><ul><ul><li>Localization can be tricky </li></ul></ul><ul><ul><li>Requires some wiki knowledge </li></ul></ul><ul><ul><li>Some effort required to encourage user contributions </li></ul></ul>
  37. 37. Questions and answers period Thank You! <ul><ul><li>Second Life: http://www.secondlife.com </li></ul></ul><ul><ul><li>Second Life Wiki: http://wiki.secondlife.com </li></ul></ul>C. Rand McKinney    rand@lindenlab.com   http://www.linkedin.com/in/crandmck

×