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

• 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.

• 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.

• 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!

• 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.

• 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

• 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

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

• 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.

• 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 .

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

• 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.

• 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.

Homepage
Middleware
Components
Interfaces & APIs
Service Grid Map-JCache Messaging Grid JavaSpaces
Data Grid Database Cache Spring
JDBC
JMS
...
(3 more)
System
Environment
Cluster
Configuration
GigaSpaces
GUI
Configuration &
Management
Space
Configuration
GigaSpaces
CLI
Security

Homepage
Service Grid
Data Grid
Middleware
Components
Interfaces & APIs
Messaging Grid JavaSpaces Map-JCache
System
Environment
Database Cache Spring JMS
Cluster
Configuration
JDBC
...
(3 more) many-to-many, not one-to-one
GigaSpaces
GUI
Configuration &
Management
Space
Configuration
GigaSpaces
CLI
Security

• Homepage (
*
)
– access to 18 subject areas in three views
• Section Page (
*
)
– overview & contents for one subject area
• Content Page (
*
)
– similar to online help topic

• 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.

• 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.

• 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 .

Wow
• 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.

• 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