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

5. 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!

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 – we’ll 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, 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.

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. Configuration & Management (administrators) Middleware Components (application designers) Interfaces & APIs (programmers) 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. Content The New Wiki Architecture Subject Areas

17. The New Wiki Architecture many-to-many, not one-to-one

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

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 Google’s 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@gmail.com, +972-50-6570046 • Jeffrey Walker: jeffrey@atlassian.com Additional Resources • Atlassian Confluence:http://www.atlassian.com/software/confluence • Atlassian Case Studyon GigaSpaces:http://www.atlassian.com/software/confluence/casestudies/gigaspaces.jsp