Confluence and Tech Writing Wikifying Documentation 14 15 January

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

Who am I? › Jon Hertzig Technical Writer, Open. Cloud LTD jonh@opencloud. com › Technical writer • contracting since 1984: Electric Ink LTD http: //electricink. co. nz • 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 Open. Cloud, LTD. Commercial in Confidence – Copyright Open. Cloud Limited 2

Who are Open. Cloud? ‘leading the way in open technology application servers for telecoms’ http: //www. Open. Cloud. com Commercial in Confidence – Copyright Open. Cloud Limited 3

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

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 La. Te. X 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… Commercial in Confidence – Copyright Open. Cloud Limited 5

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… Commercial in Confidence – Copyright Open. Cloud Limited 6

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 Commercial in Confidence – Copyright Open. Cloud Limited 7

Why Confluence? › Some investigating revealed a few nice implementations • notably Atlassian’s own online product documentation, such as: http: //confluence. atlassian. com/display/CROWD/Crowd+Document ation • some indications that using wikis for documentation was an emerging trend: http: //www. thecontentwrangler. com/article/wikis_for_documentatio n_anne_gentle_provides_some_examples • a shining example Atlassian used as case study (Gigaspaces): http: //www. atlassian. com/software/confluence/casestudies/gigaspa ces. jsp Commercial in Confidence – Copyright Open. Cloud Limited 8

Why Confluence ? (cont. ) › Open. Cloud 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’. Commercial in Confidence – Copyright Open. Cloud Limited 9

Challenges and some solutions › How to structure with “webhelp-like” features Having created lots of web-based online help over the years (using Robo. HTML 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 “pagetree 2” in Themebuilder 3. 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. Commercial in Confidence – Copyright Open. Cloud Limited 10

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. Commercial in Confidence – Copyright Open. Cloud Limited 11

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 Open. Office. Please vote for http: //jira. atlassian. com/browse/CONF-2079 Commercial in Confidence – Copyright Open. Cloud Limited 12

Examples › Access through ‘Developer Portal’ (also done with Confluence) : http: //www. Open. Cloud. com ► ‘Developer Portal’ ► ‘Product Docs’ ► ‘Rhino Documentation’ https: //developer. opencloud. com/devportal/display/RD 2 v 0/Rhino+Do 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 Commercial in Confidence – Copyright Open. Cloud Limited 13

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 email 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}. Commercial in Confidence – Copyright Open. Cloud Limited 14