Invitation to join me in webinar about Confluence and technical documentation

I’ll be presenting a session at a webinar on Thursday 12 April (in most time zones), hosted by Atlassian. The webinar is titled “Confluence as a platform for technical documentation“. We’re packing three sessions into this webinar, so it should be fun and full of information. The other presenters are Tobias Anstett from K15t Software, and Darryl Duke from Stepstone Technologies. I’d love it if you could join us. It’s free. 🙂

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, challenging the wiki software owners, and keeping the wiki at the forefront of web technology.

I think that we technical communicators can use this characteristic of wiki technology to great advantage. Technical communicators are in the thick of things. We work in diverse environments, innovate, share ideas, collaborate, and write about the latest technologies and methodologies. We need a tool that can keep up with us.

This webinar focuses on Confluence, the wiki developed and sold by Atlassian.

Webinar details

Title: Confluence as a platform for technical documentation

How to join:  Go to the webinar registration page.

Date and time: The registration page has a neat time zone converter. Here is the time in some time zones:

• US Pacific time: Thursday 12 April 2012 at 8 am
• US Eastern time: Thursday 12 April 2012 at 11 am
• Amsterdam time: Thursday 12 April 2012 at 5 pm
• Sydney time: Friday 13 April 2012 at 1 am (yes, that’s right, 1 am)

Length: 60 minutes

What’s in the webinar

People from two different plugin development companies are joining me to present parts of the webinar: Tobias Anstett from K15t Software, and Darryl Duke from Stepstone Technologies. That’s so exciting!

I’ll kick off, with a discussion of Confluence as an extensible platform.

• The extensibility and versatility of the wiki stood me in good stead recently, when I used Confluence to write and publish a book. I’ll talk about the benefits of writing on the wiki, the plugins that we added to the wiki to provide the functionality we needed to produce the book, and how we worked with the plugin developers to extend the functionality even more.
• Moving to the broader arena of technical documentation, we’ll look at some typical requirements of a documentation tool. I’ll discuss whether core Confluence functionality satisfies those requirements, and point out the plugins that we can add to give us what we need.
• I’ll also show how technical communicators can get involved in the development of wiki technology.

Next up is Tobias. The K15t team develops a number of Confluence plugins specifically for technical documentation. The company’s vision statement  is, “We believe that wiki-based technologies will be the future for documentation.” Yes! Tobias also spent a lot of time with me and Richard Hamilton, of XML Press, extending the Scroll Wiki DocBook Exporter plugin to enable us to produce a book on the wiki. It will be great to share the webinar with Tobias. His part of the session is called, “Complete the Documentation Life Cycle with K15t” and he’ll show us how to use the K15t plugins in the documentation life cycle.

Darryl will conduct the third part of the webinar, titled “Simplify and brand your Documentation with Stepstone’s Zen”. Zen Foundation is a theme that you can add to Confluence. It is available as a plugin, developed by Stepstone Technologies. A theme changes the look and feel of the wiki site, and can add significant functionality too. I’ve recently worked on the Atlassian Developers site, a Confluence site that uses the Zen Foundation theme. Darryl and the Stepstone team were great in helping us to develop the brand we wanted for that site, and in customising the theme for our needs.

Prizes too

There are some prizes to be won! When you register, your name will be entered into a draw to win one of these:

• One of 10 copies of my  new book: Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. (Thank you to Atlassian and XML Press for making these available.)
• A Zen Foundation license valued up to $12,000.
• One of K15t’s Scroll Wiki Exporters valued up to $3,600.

Questions and chat

If there’s time at the end of the webinar, we’ll open it up for questions. Come and throw them at us. 🙂

Confluence tip – speedy text formatting with keyboard shortcuts

This hint is for people who type faster than they move their mouses. Like me! It shows one of the ways of formatting text quickly (bold, italic, bullets, lists, headings) in Confluence wiki. The post could also be called “quick keys FTW”.

I’m using Confluence 4.1.9.

Keyboard shortcuts are your friend

They’re a real time saver. Click the ? on the editor toolbar to see them:

The resulting help dialog shows some of the shortcut keys:

There are more – try the usual suspects too

Most of the keyboard shortcuts will work as you expect. For example:

• Bold text: Ctrl+B or Cmd+B
• Italics: Ctrl+I or Cmd+I
• Undo: Ctrl+Z or Cmd+Z

They’re described in the Confluence documentation: Keyboard shortcuts.

My new book is available on Amazon and Barnes & Noble

Newsflash: My new book is now available at Amazon.com and Barnes & Noble. The book is titled, Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. It is about developing documentation on a wiki. It’s also about technical communicators. And chocolate.

DocBook export and import round trip with Confluence wiki

This is exciting news for technical communicators. We can export content from Confluence wiki to DocBook and then import it back into Confluence. I’ve just tried it using the Scroll Wiki DocBook Exporter and the RedHat DocBook Import for Confluence.

As you may already know, I’ve written a book. 😉 The book is about Confluence, and the content is on a Confluence site. So I decided to try exporting the book to DocBook XML and then importing it back into a different Confluence space.

In summary:

• I’m running Confluence wiki, version 3.5.3.  (The DocBook Import plugin does not yet support Confluence 4.)
• I used version 2.0.2 of the Scroll Wiki DocBook Exporter, a Confluence plugin from K15t Software, to export the content of my book to DocBook XML.
• Without making any changes to the XML, I used version 1.1.1 of RedHat’s DocBook Import for Confluence to import the content back into Confluence, in a new space that I had created for this purpose.
• There were a few hiccups, but basically it worked well.

A friendly word of warning: The DocBook Import plugin is unsupported. It was originally created for the JBoss Community Project Documentation Editor, and the developers decided to make it publicly available, free of charge. You can read about the plugin and ask questions on the JBoss Community site.

Exporting the content to DocBook XML

I used the Scroll Wiki DocBook Exporter, a Confluence plugin from K15t Software, to export the content of my book to DocBook XML. My earlier post gives quite a bit of detail on how to use the plugin: Writing a book with DocBook and a Confluence wiki. This screenshot shows the settings I used to export the pages from Confluence:

Exporting from Confluence to DocBook XML

A note: I had to use the template called “Book using preface and chapters“. When I chose the template “Book using preface, parts and appendix“, the import pulled in only the home page and the appendices. The explanation lies somewhere in the DocBook formatting, but I don’t know the details.

Importing the XML back into Confluence

I installed RedHat’s DocBook Import for Confluence plugin onto my Confluence site. Then I added a new space in Confluence, and went to the home page of that new space. The plugin adds an option to the “Tools” menu called “JBoss DocBook Importer“:

DocBook import option in Confluence Tools menu

Clicking that option invokes the importer configuration page:

DocBook Import configuration page

As we who know and love Confluence are aware, you cannot have two pages with the same name in a Confluence space. The DocBook Importer accepts a prefix that it will use to resolve such conflicts. But on my first attempt, I did not give it any prefix. I knew that all the page titles in my book were unique, so I thought the import would be good. It turned out that there was a duplicate page title, because I had used a heading level 1 to highlight the book title, and had given the page the same name as the title.

The importer gave me an error message, and I supplied a rather unimaginative prefix “123”.

Message requesting prefix to resolve duplicate page names

This time everything went smoothly. In the following screenshot, you can see the success reported by the importer on the right, and the newly-created table of contents in the left-hand panel:

Import successful

Results

Success!

• All the pages are there, with all content present.
• The images are all present.
• Tables are correctly formatted. My content includes only simple tables.
• List formatting looks good.
• Bold and italic formatting are good.
• Links are good.

One of the book's illustrations by Ryan Maddox

The above screenshot shows one of the illustrations in the book, created by Ryan Maddox and reproduced here with his permission.

A few hiccups

Some things will need fixing, either manually after each import or perhaps in a future version of the importer plugin:

• The images are larger than on the original pages.
• URLs printed on the page have acquired URL encoding rather than retaining the human-readable form.
• The Scroll Wiki DocBook Exporter plugin allows you to add information for a book index and footnotes, via special macros. The reimported pages print the content of the index or footnote entry on the page itself. For example, in the screenshot below I have highlighted an index entry at the top of the page.

Another page imported from DocBook

Thanks to the teams at K15t Software, Red Hat and the JBoss Community for these two plugins!

Using the plugins in earnest

Richard Hamilton, at XML Press, and I have used the Scroll Wiki DocBook Exporter to produce my new book. I haven’t used the DocBook Import, other than to try it out for this blog post. I’d love to know if you’re using either of these two plugins in your documentation or content management procedures. Do you have any stories or tips to share?

Pre-orders of my book available at reduced price

If you’re thinking of buying my book, now is a very good time. 🙂 Pre-ordering is available at Barnes & Noble, and they’re offering a price of just $26.96 (reduced from $39.95) for a few days.

Update (Saturday 5:15pm in Sydney): The price is now $21.57! I don’t know how long the offer lasts.

Update (Sunday 19 February): There are some problems with the Barnes & Noble page for the book – there is currently no pre-order or buy button at all. In addition, some people have received messages from B&N saying that their orders have been cancelled. Richard Hamilton at XML Press  is investigating. I’m so sorry about the confusion. I’ll let you know as soon as I hear more.

Thanks for letting me know about the problem. I hope it is sorted out quickly.

The book is called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. It’s about wikis, Confluence, technical communication, technical writers, and of course chocolate.

Follow Ganache, technical communicator extraordinaire, inside Confluence wiki for an in-depth guide to developing and publishing technical documentation on a wiki. Then, with the groundwork done, you will see how to make your wiki fly.

Experience life as a wiki author and reader. Working in an agile environment? Wikis were made for that! Wondering about search engine optimization (SEO)? Wikis can do that too. Learn how to harness the wiki’s social and collaborative features, turning technical documentation into true communication.

The book is also the confluence of technical communication and chocolate. Because you can’t have one without the other!

I hope you enjoy it. 🙂

Details

Pre-order at Barnes & Noble: http://www.barnesandnoble.com/w/confluence-tech-comm-and-chocolate-sarah-maddox/1038398637?ean=9781937434007

More details of the book at XML Press.