Online Help, the Next Generation:

1
Online Help, the Next Generation
The Making of a Wiki Documentation Portal

• Gilad David Maayan, GigaSpaces
• Jeffrey Walker, Atlassian
• STC Israel Convention 2007

2
About the Presenters

• Gilad is a technical writer and information
  architect.
• Developed a wiki documentation portal for
  GigaSpaces.
• GigaSpaces develops a software infrastructure for
  distributed applications, used by NYSE, Dow
  Jones, Deutche Bank, Lehman Brothers and other
  big financial organizations.
• Jeffrey (presenting from San Francisco) is
  President of Atlassian.
• Atlassian is a global software company with over
  5,000 customers in more than 60 countries using
  its Confluence, the enterprise wiki, and JIRA,
  the professional issue tracker.
• Atlassian is the wiki vendor GigaSpaces chose for
  its documentation portal.

3
IntroductionWhy Should We Care About Wiki?
4
Wiki Beyond the Buzzwords

• Weve all heard of Wiki, but what does it really
  mean for technical writers?
• Lets look at current uses of Wiki
• The Wikipedia an encyclopedia in which anyone
  can sign up as a writer, add entries or modify
  existing entries.
• Organizational wiki a website on a corporate
  intranet which employees use to collaborate and
  share information.
• Open-source projects communities of developers
  use wiki to share information and document their
  work.
• Cool, but
• These uses are only marginally relevant to
  technical writers.

5
Another Look at Wiki

• Lets look at a Wikis basic functionality. A
  Wiki
• manages textual and graphic content
• provides tools for editing and authoring the
  content
• allows users to view the content on their web
  browsers
• Sounds familiar?
• Lets look at the basic functionality of a
  web-based online help system (e.g. RoboHelp
  WebHelp, AuthorIT HTML, Doc-To-Help NetHelp,
  Flare Webhelp)
• manages textual and graphic content
• provides tools for editing and authoring the
  content
• allows users to view the content on their web
  browsers
• Conclusion Wiki can be used as online help, not
  only as a collaboration tool.
• And it can actually be much better at all three
  functions sourcing, authoring and presentation
  for users!

6
Wait a Minute

• Will everyone be able to edit the documentation,
  even our customers?
• Not if you have a wiki with a strong permissions
  system.
• Tech writers can control permissions for writing
  and editing on the wiki.
• Only trusted content contributors are given
  permission.
• What about offline and printed documentation
  (PDF, CHM)?
• Wikis store content as lightweight markup good
  potential for single-sourcing.
• Existing wikis provide only rudimentary export to
  Word, PDF, static HTML.
• This is a non-trivial issue well come back to
  it later.

7
Wiki Online Help Like Web Help, Only Better

• Breaks away from the tree-and-page UI paradigm
• Help pages become content portals
• Multiple views of the same content

• The Wow effect
• New and different, great first impression
• Live documentation
• New content is immediately online no need to
  generate and distribute
• Possibilities for interactivity with end-users
• Easier collaboration for tech writing team
• Anyone can edit from anywhere (with permission)
• Advanced versioning features, author tracking
• New content contributors
• Freelancers, writers in distant locations
• Developers (SMEs) can review and make changes
  online

8
Goals for this Session

• Introducing a leading Enterprise Wiki product,
  Atlassian Confluence
• Presenting a real-life implementation of
  Confluence for online help the GigaSpaces Wiki
  Documentation Portal
• Discussing the GigaSpaces migration effort what
  it took to switch from RoboHelp to wiki
• Questions and answers

9
Presenting Jeffrey Walker, President of Atlassian

• Get the Atlassian presentation
• Download the video (38MB)
• Download slides only (7MB)

10
A Real Implementation of Confluence for OLH
GigaSpaces Wiki Documentation Portal
11
GigaSpaces Wiki Documentation Portal Business
Card

• URL http//www.gigaspaces.com/wiki
• End-users programmers who develop applications
  on top of GigaSpaces.
• Trusted content contributors technical writers,
  product manager and CTO, RD team leaders
• Portal contents wiki online help, wiki release
  notes, PDF documentation, online quick start
  guide, Javadocs, code examples ( external
  content)
• Accessibility publicly available to anonymous
  users editing for selected user accounts.

12
Content Contribution Concept

• The Wiki has 25 user accounts content
  contributors get a user account with appropriate
  permissions.
• A junior tech writer gets e-mail notification on
  all content changes, checks English and
  formatting.
• New pages are restricted for external viewing,
  until approved.
• Corrections to existing pages are usually
  immediately online.
• Heavy editing is done using a Confluence plug-in
  for Eclipse, TimTam.

13
Dashboard

• Root page of the wiki where everybody starts.
• The default Confluence dashboard looks like this
• The customized GigaSpaces dashboard looks like
  this ()

14
Online Help Architecture

• GigaSpaces product is complex, with dozens of
  special subject areas.
• Old OLH had a huge tree with 9 hierarchical
  levels.
• To simplify, we defined three views of the
  content.

15
Online Help Architecture

• GigaSpaces product is complex, with dozens of
  special subject areas.
• Old OLH had a huge tree with 9 hierarchical
  levels.
• To simplify, we defined three views of the
  content.

• Content overlaps between the views.
• The idea different users need the same content
  in a different context.

16
The New Wiki Architecture
Subject Areas
17
The New Wiki Architecture
many-to-many, not one-to-one
18
Lets See What it Looks Like

• Homepage () access to 18 subject areas in
  three views

• Section Page () overview contents for one
  subject area

• Content Page () similar to online help topic

19
The Migration EffortWhat it Took to Switch from
RoboHelp to Confluence
20
The First Step Wiki Portal Alongside RoboHelp

• Initially, the wiki homepage and 18 section pages
  were built, with all links going to help topics
  in the old WebHelp.
• For about a month, customers accessed the
  documentation through the wiki section pages, but
  most of the content remained in RoboHelp.
• This approach had several advantages
• Took only a few weeks to set up.
• Enabled employees and customers to try the wiki
  user experience.
• Enabled easy rollback to the old RoboHelp system.
• The trial period was a huge success, so it was
  decided to drop the RoboHelp platform and move
  all content to the wiki.

21
Importing Existing Content

• The challenge
• 1200 pages of online help in RoboHelp WebHelp
  format
• No built-in HTML import tools, existing plug-ins
  are unsuitable
• Four-step conversion for every page (HTML to wiki
  markup, changing page title, creating new page,
  attaching images)
• The solution
• Developing a software tool that automates
  conversion and inserts pages into wiki using
  Confluence API.
• Tech writing team manually reviewed all pages and
  corrected formatting errors.
• Finally, links in section pages were changed to
  go to the new wiki pages.
• The import project took 3 months when it ended,
  the RoboHelp platform was decommissioned.

22
Enabling PDF Documentation

• The challenge Confluence offers export to Word
  and PDF, but
• Limited control over styles and page layout
• No control over the order of content in the PDF
  document
• Insufficient indication of content hierarchy
• No professional front matter (cover, TOC, etc.)
• The solution
• Creating single wiki page that collates all wiki
  content, in desired order.
• Exporting to Word the using built-in export.
• Developing Word macro that reformats and adds
  front matter
• Generating PDF from the Word document
• Published as free plug-in Confluence PDF
  Documentation Generator.

23
Efforts Pay Off The Wow Effect

• GigaSpaces old RoboHelp documentation was
  heavily criticized.
• The move to wiki caused a dramatic change
  without significant changes to content
• An analyst at Branham group wrote That wiki is
  amazing!
• GigaSpaces CEO called it a revolution in how
  GigaSpaces explains itself to the world.
• GigaSpaces EMEA Sales Manager said new customers
  are blown away.
• Featured as a case study by Atlassian.
• A big success by objective measures
• Over a thousand page views per day.
• Appears on Googles first page for many technical
  searches.
• Used extensively inside the company by support,
  developers, new employees.

24
Questions Answers
25
Contact Details and Additional Resources

• Gilad David Maayan gilad.maayan_at_gmail.com,
  972-50-6570046
• Jeffrey Walker jeffrey_at_atlassian.com
• Additional Resources
• Atlassian Confluence http//www.atlassian.com/so
  ftware/confluence
• Atlassian Case Study on GigaSpaces
  http//www.atlassian.com/software/confluence/cases
  tudies/gigaspaces.jsp