1 Confluence and Tech Writing Wikifying Documentation Jon Hertzig – Technical Writer 14/15 January, 2009

2 Commercial in Confidence – Copyright OpenCloud Limited Who am I? › Jon Hertzig Technical Writer, OpenCloud LTD › Technical writer contracting since 1984: Electric Ink LTD first in New York, clients mostly for Wall St (some of which are recently defunct!) but also others such as United Nations, Museum of TV & Radio, Glaxo, Unilever… then in Wellington, New Zealand, where I’ve lived since 2000, and wrote and edited various kinds of documentation for many national and international government and business organisations now working for OpenCloud, LTD.

3 Commercial in Confidence – Copyright OpenCloud Limited Who are OpenCloud? ‘leading the way in open technology application servers for telecoms’

4 Commercial in Confidence – Copyright OpenCloud Limited Why they hired me › Customers couldn’t find information that “was in the documentation” › Written by developers, using tools such as LaTex and Docbook › Compiled into a gargantuan, dense, not-particularly-attractive PDF:

5 Commercial in Confidence – Copyright OpenCloud Limited More on why a monstrous PDF didn’t work... › Information not sorted by product, or for each audience (developers, administrators, other users) › Not easily maintainable (you’d have to learn LaTeX to change it) › Not available online — static (any revisions only available with each release of the product) › Not collaborative (each section of the document written in isolation) — so hard to keep consistent, comprehensive, accurate…

6 Commercial in Confidence – Copyright OpenCloud Limited Why a wiki? › Overriding need: make information accessible › Highly technical content, requiring collaboration not stuff I could write (or even understand a lot of!) but desperately needing editing written by brilliant people who were: too close to it, might think in numbers and symbols (and bits and bytes) more than words, for some of whom English is a second language (without a clear API) in an environment with developers across the office and around the globe, on various platforms, contributing and reviewing each others’ work. › Solve shortcomings of the humongous PDF make it collaborative, dynamic, maintainable, online, categorisable, navigable…

7 Commercial in Confidence – Copyright OpenCloud Limited Why not a wiki? › Wikis have a reputation for growing organically (like weeds) would need to make sure we could tame it › Would it work with my biases for tech writing: plain English and Information Mapping™ ? to structure and present information in a way that is easy to grasp and navigate

8 Commercial in Confidence – Copyright OpenCloud Limited Why Confluence? › Some investigating revealed a few nice implementations notably Atlassian’s own online product documentation, such as: ation ation some indications that using wikis for documentation was an emerging trend: n_anne_gentle_provides_some_examples n_anne_gentle_provides_some_examples a shining example Atlassian used as case study (Gigaspaces): ces.jsp ces.jsp

9 Commercial in Confidence – Copyright OpenCloud Limited Why Confluence ? (cont.) › OpenCloud was already using Confluence in-house, for communicating across the organisation The developers were familiar with the product, wiki markup, processes for using it. Integrated well with internal tools, including JIRA. Large community support, plugins, customisation, extensibility. Tied in with the upcoming ‘Devportal’.

10 Commercial in Confidence – Copyright OpenCloud Limited Challenges and some solutions › How to structure with “webhelp-like” features Having created lots of web-based online help over the years (using RoboHTML and other tools), I decided it was important to have features such as a the collapsible TOC and search box. › Solution: Themebuilder 3 After experimenting with many solutions, settled on using “pagetree2” in Themebuilder3. This product, from Adaptavist, has been fantastic for getting the site to look the way we want. That and having lots of developers around to tweak things, create macros, and suggest ways of using CSS.

11 Commercial in Confidence – Copyright OpenCloud Limited Challenges and solutions (cont.) › Audit trail, security, and approval process Needed to keep track of changes, control access to different drafts, and log the revision cycle. › Solution: logins and plugins Confluence has excellent facilities for keeping and comparing all versions of a page, and authorisation to different spaces. We use the Approvals/Workflow plug-ins to record reviews and publish from a staging to a public space upon final approval.

12 Commercial in Confidence – Copyright OpenCloud Limited Challenges and solutions (cont.) › Export to PDF and/or HTML Needed a version of the documentation to deliver on disc. › Solution: PDF workarounds Some formatting, such as cloaks and tabs, didn’t export well to HTML. Never found a satisfactory workaround. Controls over PDF formatting not great, and using external plugins requiring exporting to Word too cumbersome. In the end, produced (barely) acceptable PDFs by customisation in Confluence, and re-formatting pages based on how they export, and combining with covers and TOCs created in OpenOffice. Please vote for

13 Commercial in Confidence – Copyright OpenCloud Limited Examples › Access through ‘Developer Portal’ (also done with Confluence) : ► ‘Developer Portal’ ► ‘Product Docs’ ► ‘Rhino Documentation’ cumentation cumentation Documentation set home: standard features include pagetree (TOC/search), navigation icons, lozenges, copyright / glossary / links / comments Document home: title page, standard features include summary box, PDF link, Topics, Audience and Scope, global left sidebar features, tree and search starting from document home

14 Commercial in Confidence – Copyright OpenCloud Limited Examples (cont.) › Document page: common features include tabs ({deck} and {card} from the {composition-setup} plugin, to allow maximum scannability, to grasp what’s on a page quickly and be able to drill down › Markup/workflow example in the staging space, note comments… edit (see use of metadata) / page info (versions) / changes / history (compare versions) / how to create a new page using metadata template?, approvals (with notification, labels…) › Complex example: IN Benchmarks, amasses about 50 pages of information into one. Uses macros such as {card}, {deck}, {ocpanel}, {tip}, {warning}, {chart}, {ctable}, {toggle-cloak}, {show-if}.