Date post: | 27-Dec-2015 |
Category: |
Documents |
Upload: | myron-cunningham |
View: | 217 times |
Download: | 0 times |
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.
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)
• 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 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.
Contact Details and Additional Resources
• Gilad David Maayan: [email protected], +972-50-6570046
• Jeffrey Walker: [email protected]
Additional Resources
• Atlassian Confluence:
http://www.atlassian.com/software/confluence
• Atlassian Case Study on GigaSpaces:
http://www.atlassian.com/software/confluence/casestudies/gigaspaces.jsp