Online Help, the Next Generation:

Gilad David Maayan, GigaSpaces

Jeffrey Walker, Atlassian

STC Israel Convention 2007

The Making of a Wiki Documentation Portal

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.

IntroductionWhy Should We Care About Wiki?

Wiki – Beyond the Buzzwords

• We’ve all heard of Wiki, but what does it really mean for technical writers?

• Let’s 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.

Another Look at Wiki

• Let’s look at a Wiki’s 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?

• Let’s 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!

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 – we’ll come back to it later.

• 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

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

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

Presenting Jeffrey Walker, President of Atlassian

Get the Atlassian presentation:

• Download the video (38MB)

• Download slides only (7MB)

A Real Implementation of Confluence for OLH GigaSpaces Wiki Documentation Portal

• 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, R&D 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.

GigaSpaces Wiki Documentation Portal: Business Card

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.

Dashboard

• Root page of the wiki – where everybody starts.

• The default Confluence dashboard looks like this:

• The customized GigaSpaces dashboard looks like this (*)

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.

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.

Middleware Components

)application designers(

Interfaces & APIs

)programmers(

Configuration & Management

)administrators(

• Content overlaps between the views.

• The idea: different users need the same content in a different context.

Co

nten

tThe New Wiki Architecture

Homepage

Middleware Components

Interfaces & APIsConfiguration&

Management

Service Grid Messaging Grid

Data Grid Database Cache

JavaSpaces Map-JCache

Spring JMS

JDBC

System Environment

Space Configuration

Cluster Configuration

GigaSpaces CLI

...)3 more(

GigaSpaces GUI

Security

Su

bject A

reas

Homepage

Middleware Components

Interfaces & APIsConfiguration&

Management

Service Grid Messaging Grid

Data Grid Database Cache

JavaSpaces Map-JCache

Spring JMS

JDBC

System Environment

Space Configuration

Cluster Configuration

GigaSpaces CLI

...)3 more(

GigaSpaces GUI

Security

The New Wiki Architecture

many-to-many, not one-to-one

Homepage

Middleware Components

Interfaces & APIs

Configuration &Management

Service GridMessaging

Grid

Data GridDatabase

Cache

JavaSpaces Map-JCache

Spring JMS

JDBC

System Environment

Space Configuration

Cluster Configuration

GigaSpaces CLI

...)3 more(

GigaSpaces Browser

Security

Let’s 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

Homepage

Middleware Components

Interfaces & APIs

Configuration &Management

Service GridMessaging

Grid

Data GridDatabase

Cache

JavaSpaces Map-JCache

Spring JMS

JDBC

System Environment

Space Configuration

Cluster Configuration

GigaSpaces CLI

...)3 more(

GigaSpaces Browser

Security

Homepage

Middleware Components

Interfaces & APIs

Configuration &Management

Service GridMessaging

Grid

Data GridDatabase

Cache

JavaSpaces Map-JCache

Spring JMS

JDBC

System Environment

Space Configuration

Cluster Configuration

GigaSpaces CLI

...)3 more(

GigaSpaces Browser

Security

The Migration EffortWhat it Took to Switch from RoboHelp to Confluence

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.

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.

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.

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 Google’s first page for many technical searches.

– Used extensively inside the company by support, developers, new employees.

Questions & Answers

Contact Details and Additional Resources

• Gilad David Maayan: gilad.maayan@gmail.com, +972-50-6570046

• Jeffrey Walker: jeffrey@atlassian.com

Additional Resources

• Atlassian Confluence:

http://www.atlassian.com/software/confluence

• Atlassian Case Study on GigaSpaces:

http://www.atlassian.com/software/confluence/casestudies/gigaspaces.jsp