Presentation given in an Atlassian webinar, 12/13 April 2012. It's about Confluence wiki as an extensible platform, and how technical communicators can take advantage of the wiki's extensibility.
MAHA Global and IPR: Do Actions Speak Louder Than Words?
Confluence as platform for technical documentation
1. Confluence as a Platform for Technical Documentation
Sarah Maddox (Atlassian)
Confluence as a platform for technical
communication
Tobias Anstett (K15t Software)
Complete the documentation life cycle
Darryl Duke (Stepstone Technologies)
Simplify and brand your documentation
wikitechcomm.onconfluence.com Atlassian webinar, 12 April 2012
Confluence as a Platform for Technical Documentation, by Sarah Maddox 1
2. Overview of Sarah’s presentation
• Confluence as extensible platform
• Developing a book on a wiki
• A platform for technical communicators
• Add-ons for enhanced functionality
• Driving wiki development
Confluence as a Platform for Technical Documentation, by Sarah Maddox 2
3. Wiki as extensible platform
Confluence as a Platform for Technical Documentation, by Sarah Maddox 3
4. Wiki as extensible platform
Extensible
Versatile
Ecosystem
Confluence as a Platform for Technical Documentation, by Sarah Maddox 4
5. Wiki as extensible platform
Extensible Atlassian: Core Confluence
Versatile Community developers: Add-ons
Ecosystem Experts: Integrations and services
Confluence as a Platform for Technical Documentation, by Sarah Maddox 5
6. Wiki as extensible platform
Extensible Atlassian: Core Confluence
Versatile Community developers: Add-ons
Ecosystem Experts: Integrations and services
Customers
Confluence as a Platform for Technical Documentation, by Sarah Maddox 6
7. Confluence, Tech Comm, Chocolate
A wiki as platform extraordinaire for technical communication
Wikis and technical documentation
Agile environments
Social media
Crowd sourcing
Driving wiki development
And more
wikitechcomm.onconfluence.com
Confluence as a Platform for Technical Documentation, by Sarah Maddox 7
8. Producing a book on a wiki
Confluence as a Platform for Technical Documentation, by Sarah Maddox 8
9. Developing the book on the wiki
Dogfood
Location
Diagrams
Collaboration
Confluence as a Platform for Technical Documentation, by Sarah Maddox 9
10. Developing the book on the wiki
Dogfood Author
Location Reviewers
Diagrams Copy Editor
Collaboration Artist
Confluence as a Platform for Technical Documentation, by Sarah Maddox 9
12. Cool, so now the book is on the wiki
Confluence as a Platform for Technical Documentation, by Sarah Maddox 11
13. How to get from the wiki to production
?
Confluence as a Platform for Technical Documentation, by Sarah Maddox 12
14. Scroll Wiki DocBook Exporter
www.k15t.com
Confluence as a Platform for Technical Documentation, by Sarah Maddox 13
15. Technical communicators
Keep up with new Work in diverse Collaborate
technology and environments
methodology
Share Ideas
Innovate
Confluence as a Platform for Technical Documentation, by Sarah Maddox 14
16. Technical communicators
Skilled Passionate
Experienced
Full of ideas
Confluence as a Platform for Technical Documentation, by Sarah Maddox 15
17. Technical communicators
Need a tool that
can keep up with us
Confluence as a Platform for Technical Documentation, by Sarah Maddox 16
19. Add-ons for enhanced workflow
• Configurable workflows
• Shared workflows
www.comalatech.com • Content publishing
• Live forms
www.frevvo.com • Conditional routing
• Digital signatures
And more
Confluence as a Platform for Technical Documentation, by Sarah Maddox 18
20. Look and feel with core Confluence
Confluence as a Platform for Technical Documentation, by Sarah Maddox 19
21. Look and feel with core Confluence
Themes Logos
CSS Velocity layouts
Color Schemes Site home page
Confluence as a Platform for Technical Documentation, by Sarah Maddox 20
22. Look and feel with theme plugins
• Zen Foundation
• RefinedWiki
• Builder
• TechTime Blog
• BlackBerry
• iPhone and iPod Touch
• And more plugins.atlassian.com
Confluence as a Platform for Technical Documentation, by Sarah Maddox 21
24. Single source publishing
No wiki is an island
Confluence as a Platform for Technical Documentation, by Sarah Maddox 23
25. Importing content into Confluence
Import Format Tool
Another Confluence The Confluence XML export and import tools are useful for
wiki downloading the content of a space, or an entire site, and uploading
it into another Confluence site.
Other wikis The Universal Wiki Converter is a standalone tool that assists in
converting pages to Confluence format from other wiki formats.
Microsoft Word Confluence's built-in Office Connector imports a Word document and
converts it to one or more wiki pages based on the criteria you
define. It processes one Word document at a time.
WebWorks ePublisher provides a set of standalone tools for
converting Word documents to Confluence, based on custom styles
and formats. Batch processing and scheduling are available.
Confluence as a Platform for Technical Documentation, by Sarah Maddox 24
26. Importing content into Confluence
Import Format Tool
Adobe FrameMaker WebWorks ePublisher converts FrameMaker documents to
Confluence
DITA XML DITA2wiki is a standalone tool that converts DITA XML documents to
Confluence format and uploads them into the wiki via a set of Ant
commands.
WebWorks ePublisher offers a set of standalone tools for conversion
and import from DITA XML to Confluence wiki.
DocBook XML The DocBook import plugin is a Confluence plugin that converts
DocBook XML to wiki format and imports the pages into a
Confluence space.
Confluence as a Platform for Technical Documentation, by Sarah Maddox 25
27. Exporting content from Confluence
Export Format Tool
Another Confluence The Confluence XML export and import tools are useful for downloading the
wiki content of a space or an entire site and uploading it into another Confluence site.
Print The browser's print option will print a Confluence page. Export to PDF for
sophisticated printing options.
PDF Confluence's built-in PDF export converts a selected page or pages into a single
PDF file and provides customized layout and stylesheets.
Scroll Wiki PDF Exporter, a Confluence plugin, offers a PDF export with flexible
themes for configuring layout and styles.
Microsoft Word Confluence's built-in Word export performs a basic conversion of wiki content to
HTML and applies some predefined Word CSS stylesheets. It processes just one
page at a time.
Scroll Office is a Confluence plugin that exports Confluence pages to Word based
on custom templates. You can export a single page or a hierarchy of pages.
Confluence as a Platform for Technical Documentation, by Sarah Maddox 26
28. Exporting content from Confluence
Export Format Tool
DocBook XML Scroll Wiki DocBook Exporter is a Confluence plugin that converts a
selected page or pages to DocBook XML.
HTML Confluence's built-in HTML export converts a single page, a selection of
pages, or an entire space to HTML.
The Scroll Wiki HTML Exporter is a Confluence plugin that exports
content from Confluence pages to styled HTML files.
Eclipse Help The Scroll Wiki EclipseHelp Exporter is a Confluence plugin that exports
content from Confluence to Eclipse Help format.
JavaHelp The Scroll Wiki JavaHelp Exporter is a Confluence plugin that exports
content from Confluence to JavaHelp format.
EPUB The Scroll Wiki EPUB Exporter is a Confluence plugin that exports
Confluence pages to EPUB format.
Confluence as a Platform for Technical Documentation, by Sarah Maddox 27
29. Many, many more add-ons
• Content reuse
• Metadata
• Templates
• Diagrams and mockups
• Social media integration
• Website and application integration
• You name it
plugins.atlassian.com
Confluence as a Platform for Technical Documentation, by Sarah Maddox 228
30. Confluence CLI by Bob Swift
https://plugins.atlassian.com/plugins/org.swift.confluence.cli
Confluence as a Platform for Technical Documentation, by Sarah Maddox 29
31. Plugins in Atlassian OnDemand
http://confluence.atlassian.com/display/AOD/Atlassian+OnDemand+Plugin+Policy
Team Calendars (commercial)
Gliffy (commercial)
Content Formatting Macros (free)
Table Plugin (free)
Confluence as a Platform for Technical Documentation, by Sarah Maddox 30
32. How the book deals with Plugins
• Detailed in the content
• Listed at end of every chapter
• Introduced in chapters 2 and 4
• Extolled in chapter 23: Driving wiki development
wikitechcomm.onconfluence.com
Confluence as a Platform for Technical Documentation, by Sarah Maddox 31
33. Wiki as extensible platform
Extensible Atlassian: Core Confluence
Versatile Community developers: Add-ons
Ecosystem Experts: Integrations and services
Customers
Confluence as a Platform for Technical Documentation, by Sarah Maddox 6
34. Driving wiki development
Extensible Atlassian: Core Confluence
Versatile Community developers: Add-ons
Ecosystem Experts: Integrations and services
Confluence as a Platform for Technical Documentation, by Sarah Maddox 33
35. Driving wiki development
Raise requests:
http://jira.atlassian.com
Join a user group:
http://www.atlassian.com/company/community
Contact Atlassian:
http://www.atlassian.com/company/contact
Contact a plugin developer:
http://plugins.atlassian.com
Confluence as a Platform for Technical Documentation, by Sarah Maddox 34
36. Developing add-ons yourself
Write a user macro:
http://confluence.atlassian.com/display/DOC/Writing+User+Macros
Develop a plugin:
https://developer.atlassian.com/display/DOCS/Developing+with+the+Atlassian
+Plugin+SDK
Interact with the APIs:
https://developer.atlassian.com/display/CONFDEV/Confluence+Developer+Do
cumentation
Confluence as a Platform for Technical Documentation, by Sarah Maddox 35
37. Getting hold of the book
Wiki:
https://wikitechcomm.onconfluence.com
Amazon.com:
http://www.amazon.com/
Confluence-Tech-Chocolate-Sarah-Maddox/dp/1937434001
Barnes & Noble:
http://www.barnesandnoble.com/w/confluence-tech-comm-chocolate-sarah-
maddox/1108812996?ean=9781937434007
XML Press:
http://xmlpress.net/publications/chocolate/
Confluence as a Platform for Technical Documentation, by Sarah Maddox 36
Hinweis der Redaktion
Speaker’s notes: Introductory slideWhen the webinar starts:Welcome everyone.Welcome the guys from K15t Software and Stepstone Technologies, who will be giving demos during the webinar.Explain the format of the webinar.Sarah’s introduction:I’m excited about this webinar, because it’s about an aspect of wikis that I’ve come to see as very important: the fact that wikis are extensible, versatile, and built to be so. As a result, there’s a community of enthusiastic developers and innovators who devote a good deal of time to extending wiki functionality. They challenge the wiki software owners, and keep the wiki at the forefront of web technology.I think that we technical communicators can use this characteristic of wiki technology to great advantage.
Speaker’s notes: Overview of Sarah’s presentationThis is an overview of my section of the webinar.I’ll start off with an introduction to Confluence as an extensible platform.I’ll show you how I recently worked with a publishing team and a plugin development team to write and publish a book on a wiki. This is a good example of how we can take advantage of the extensibility of the wiki.Then we’ll broaden our view, to technical communicators in general and the sort of platform we need.We’ll see some specific examples of plugins and add-ons for Confluence, and we’ll discuss how we can contribute to wiki development and help ensure that it goes the way we want it to go.
Speaker’s notes: Wiki as extensible platformConfluence is a wiki. In essence, this means that Confluence displays web pages with a magic edit button. Wikis have moved on since the early days, where editing a page was their main offering. Now they do a lot more. Even so, most people who use Confluence will see the web interface. They will read the wiki pages, edit or comment on the pages, and interact with the content in other ways.Looked at from another point of view, Confluence is also a configurable platform.Administrators can adjust the look and feel, and enable or disable parts of the functionality.But there’s more, and this is the crux of this webinar: Confluence is an extensible platform.Developers can build plugins or other add-ons that people can install into Confluence.These add-ons can significantly change the way people experience the wiki.The Atlassian Plugin Exchange is a website where developers can make their plugins and add-ons available to customers. It’s also a place where customers can look for and download the add-ons they need.
Speaker’s notes: Wiki as extensible platformWhat I'm proposing is that versatility and extensibility are strong points of a wiki, often not given enough emphasis when people are considering the choice of a tool.Also, perhaps people who already have a wiki are not as aware of these points as they could be. There’s an ecosystem of people around the wiki, offering development services as well as advisory services.
Speaker’s notes: Wiki as extensible platform1) The Atlassian developers build the core Confluence features, and they also put significant effort into building and maintaining the hooks that make extensions possible.Plugin frameworkJava APIsRemote APIsOther innovative add-on points such as user macros, remote add-ons and SpeakEasy extensions.2) The community plugin developers (ecosystem) write add-ons and extensions.3) Experts write integrations and provide consultative services.
Speaker’s notes: Wiki as extensible platformCustomers make use of the tools and services provided by all three.Let’s take a look at a specific example of extending the wiki: Writing and publishing a book.
Speaker’s notes: Introducing the bookFirst, a quick overview of the book and what’s in it.(Discuss each point on the slide.)
Speaker’s notes: Producing a book on a wikiTo produce and publish the book, I worked with Richard Hamilton at XML Press. Here’s a quick overview of how we went about it:I wrote the book on Confluence, and the editorial team joined me there too.We exported the content from Confluence to DocBook XML.The publisher pushed the DocBook through some XSLT conversions to produce a PDF file, which he then sent to the printers.The publisher is also in the process of converting the DocBook to Kindle and EPUB formats, for the ebook sales.
Speaker’s notes: Developing the book on the wikiThe idea of writing the book on the wiki was immediately appealing.Dogfood: It was just cool to write a technical book on a wiki about writing technical documentation on a wiki. Meta!Location: Provided I had online access, I could pick up the writing anywhere, anytime.Diagrams: There was a neat diagram tool already available: Gliffy. In fact, the Gliffy team gave me a free licence. I didn’t need any proprietary drawing tools, and again I could do the work anywhere, anytime.Collaboration: (next slide)
Speaker’s notes: Developing the book on the wikiCollaboration: Producing a book is a team effort right from the start.I wrote the content on the wiki. Entirely.The technical reviewers conducted their review on the wiki. We chatted via comments, and I updated the pages with the resulting feedback.The copy editor worked on the wiki pages, and I watched his updates using wiki watches, and tweaked the content further.The illustrator interacted with us there too, uploading his images and iterating through the designs until we were all happy.
Speaker’s notes: Gliffy for diagramsIt was a great experience drawing diagrams for the book.Gliffy is easy to use, and very familiar to anyone who has used desktop drawing tools.Pleasant styles and images.Draw anywhere, anytime, because the Gliffy drawing canvas loads in the web page.Gliffy makes image files available that you can provide to the publisher for printing.
Speaker’s notes: Scroll Wiki DocBook ExporterThis is the first time anyone has written a book on Confluence and then used DocBook in the production processes.The Scroll Wiki DocBook Exporter is a plugin developed by K15t Software. The plugin already existed, but we needed additional functionality to support book production.The K15t team were kind enough to give me a free license for the plugin. Thanks guys!The publisher and I worked with K15t Software to extend the functionality of the plugin:IndexingImage captionsFootnotesThat was a very interesting and rewarding experience. It’s a great example of how we can bend the wiki to our will!
Speaker’s notes: Technical communicatorsMoving on from the use case of the book, let’s broaden the discussion to talk about technical communicators and a wiki.Technical communicators...
Speaker’s notes: Technical communicatorsWe need a tool that can keep up with us.Out of the box, the core Confluence functionality gets us a fair way along the track.You will probably need to add plugins to tailor the wiki to your requirements.Each person works in a different environment, and has different requirements.Let’s look at some technical documentation requirements to see what the core Confluence functionality provides, and the plugins available to extend it:WorkflowLook and feelSingle source publishing
Speaker’s notes: Workflow using core ConfluenceOut of the box, Confluence provides enough functionality to support a simple workflow:Draft, review, publish.It’s what we have been using at Atlassian for years!Draft:Create the page, and hide it with page restrictions. Use the page restrictions to make the page visible to the groups of people who should see it when in draft. In our case, we make draft pages visible to and editable by all Atlassian staff.Collaborate with SMEs and technical writing team to finalise the draft.Review:Extend the page restrictions if necessary.Allow reviewers to comment on and/or edit the page.Request reviews of the page.Collaborate to finalise the content.Publish:Remove the page restrictions.This workflow can be cumbersome when dealing with large volumes of content.The workflow is also inadequate in more restricted environments, where legislative and regulatory requirements dictate a more complex workflow.
Speaker’s notes: Look and feel with core ConfluenceThemes provide the primary way of adjusting the look and feel of your Confluence site. A theme is a bit like a browser skin. It changes the colours, font styles, and backgrounds. A theme can also add new options to the wiki functionality.Out of the box, Confluence comes with three themes:DefaultEasy ReaderDocumentationThe screenshot shows the documentation theme, which provides:A pleasant, sober style suited to documentation.Configurable page header and footer.Configurable left-hand navigation panel.A few other bits and bobs.
Speaker’s notes: Look and feel with core ConfluenceOut of the box, you can also adjust:CSSColour schemesSpace and site logosVelocity layoutsSite home page
Speaker’s notes: Look and feel with theme pluginsIf you need more flexibility, you can add a theme plugin. Here are some examples.
Speaker’s notes: Zen Foundation themeThe Atlassian Developers site uses the Zen Foundation theme. It’s highly configurable and flexible, and allows you to create a wiki site that feels like a website.Darryl Dukeof Stepstone Technologies will be giving a demo of the Zen theme later in this session.
Speaker’s notes: Single source publishingTechnical communicators often need to import content into the wiki from other formats, and to export it out of the wiki into the formats that our customers can read.When pulling content into the wiki, we want to accept as many formats as possible. We need to get content out of the wiki into a standard, portable format. Four years ago, when I first became acquainted with a wiki, options were decidedly limited. Since then plugin developers have worked wonders. They have started building the technology that technical communicators get excited about.
Speaker’s notes: Many, many more add-onsWe’ve looked at just three scenarios, and the add-ons available to cater for them. There are many many more add-ons. This slide shows some of the categories relevant to technical documentation. Search the Atlassian Plugin Exchange to see what’s available.
Speaker’s notes: Confluence CLI by Bob SwiftThis is a special mention of an extremely useful tool developed by Bob Swift. It’s not a plugin, but rather a command line interface that uses the Confluence remote APIs. You can run it from your local PC. Just unzip it, give it the address of the Confluence server and a username/password to work with, and then pass it commands to update pages in bulk.I’ve used it in the past to delete a number of unwanted pages from our developer wiki.We’re also considering another use case that would incorporate the CLI into our regular processes, involving updating the documentation for product releases. If we do decide to do this, I’ll blog about it.
Speaker’s notes: Plugins in Atlassian OnDemandThis is a quick note about Atlassian OnDemand, and the limitations of plugins and add-ons in this environment.Atlassian OnDemand is a service offering a hosted instance of Confluence and other Atlassian applications.Atlassian OnDemand comes with a set of pre-defined plugins. You cannot install new plugins or remove existing plugins. The commercial and bundled plugins listed on this slide are included with the service. You can enable, disable and configure them via your OnDemand administration console.What about the future of plugins and add-ons for Atlassian OnDemand? The Atlassian engineering team is working on the design for an infrastructure that will support add-ons better. They are working with add-on developers to get something ready as soon as possible. The current thinking is to provide a framework for remote applications to integrate with and interact with the applications in OnDemand. Stay tuned for information.
Speaker’s notes: How the book deals with pluginsBefore we go on, I’d like to tell you how the book deals with plugins, add-ons and other tools.Each chapter of the book deals with a particular use case, such as exporting content, reusing content, and so on. The book describes the core wiki functionality for each use case. Where relevant, it gives details of the plugins and other tools that are useful too.At the end of every chapter is a list of plugins and tools that are relevant to the use cases covered in that chapter.Chapter 2 introduces plugins in general, what they are and who builds them. Chapter 4 describes planning your wiki and deciding whether you need to install plugins to get the functionality you need.Chapter 23 is all about driving wiki development. (Lead into next slide.)
Speaker’s notes: Wiki as extensible platform(Repeat of earlier slide.)At the beginning of the presentation, we saw how customers make use of the core wiki functionality as well as the add-ons and extensions provided by the community and experts. As technical communicators...
Speaker’s notes: Driving wiki developmentAs technical communicators, we are customers too.More than that, we can be drivers of wiki development. We have the skills, knowledge and passion. We know what we need, and we know a lot about what needs to happen to make the platform satisfy our requirements.We can work with the ecosystem to drive wiki development. Take advantage of the skilled and enthusiastic group of add-on developers, and let them take advantage of our knowledge and passion too.We can let Atlassian know what we need, by joining user groups, logging issues on the wiki, and joining discussion wherever we can.We can also do some development of our own.