1 confluence and tech writing wikifying documentation jon hertzig – technical writer 14/15...

1

Confluence and Tech WritingWikifying Documentation

Jon Hertzig – Technical Writer

14/15 January, 2009

2Commercial in Confidence – Copyright OpenCloud Limited

Who am I?

› Jon HertzigTechnical Writer, OpenCloud [email protected]

› Technical writer

• contracting since 1984: Electric Ink LTDhttp://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 OpenCloud, LTD.


Who are OpenCloud?

http://www.OpenCloud.com

‘leading the way in open technology application servers for telecoms’


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:


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…


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…


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


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+Documentation

• some indications that using wikis for documentation was an emerging trend: http://www.thecontentwrangler.com/article/wikis_for_documentation_anne_gentle_provides_some_examples

• a shining example Atlassian used as case study (Gigaspaces): http://www.atlassian.com/software/confluence/casestudies/gigaspaces.jsp


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


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.


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.


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

http://jira.atlassian.com/browse/CONF-2079


Examples

› Access through ‘Developer Portal’ (also done with Confluence) :

http://www.OpenCloud.com ► ‘Developer Portal’ ► ‘Product Docs’

► ‘Rhino Documentation’

https://developer.opencloud.com/devportal/display/RD2v0/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


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

1 confluence and tech writing wikifying documentation jon hertzig – technical writer 14/15...

Documents

accurate slide

navigable slide

online product documentation

information accessible

information mapping

present information

technical content

available online static