A book about technical communication on Confluence wiki

Big news: I’m writing a book! It’s about developing technical documentation on a wiki, and specifically about Confluence. I started the project six months ago. Now the content is written and the technical review is about to start! Exciting and scary, all at once.

This is the title of the book:

Confluence, tech comm, chocolate

A wiki as platform extraordinaire for technical communication

It will be published in early 2012 by Richard Hamilton at XML Press.

What’s in it?

The book is primarily a guide to developing technical documentation on Confluence. But that’s not all. There are ideas and philosophies, tips and tricks, and special notes for technical writers about why a wiki is the tool we dream of. Many of the ideas apply to wikis in general, although the book focuses on Confluence because that’s the one I know best.

It’s a book for technical communicators, from someone who knows and loves them. It’s also for product owners, CEOs, developers and anyone else who is considering a wiki as a platform for technical communication.

The first part of the book introduces wikis and Confluence. Part 2 is an in-depth guide to developing technical documentation on Confluence. It starts with planning and design, moves on to developing content, through workflow all the way to release management. The more esoteric concepts are there too, such as content reuse, structure, style and online help. In part 3 we see what it’s like to work on a wiki. The book finishes with a section crammed with ideas. It’s all about making the most of the unique features that a wiki provides, to turn your documentation into technical communication extraordinaire.

Just in case you’re wondering: This isn’t an Atlassian project. It’s all my own, though of course Atlassian management and my closest colleagues know about it. It will be fun to see what other Atlassians have to say when they see the book. And when they see this post.

By the end of the book you will know everything I’ve learned in the past four years of working on a wiki. Oh, and chocolate plays a part too.

More coming soon

The illustrations are done. I love them! We’re about to start the cover design. I’ll show it to you as soon as it’s ready.

Who’s in the book?

There are even some characters in the book. I’ll introduce you to them soon. Watch this blog.

How to find an image location in the Confluence 4.0 editor

The image properties panel in the Confluence 4.0 editor does not show the location of the image. By location, I mean the page to which the image is attached, or the URL of the image source. This is a problem especially if, like many technical writers, you put a collection of often-used images in one location and then display them on a number of pages. I’ve found a workaround, though cumbersome. If you have a better one, please let me know.

In Confluence 3.5, the location was visible in the wiki markup. I’ve logged an issue about the problem in Confluence 4.0: CONF-23945. Keep an eye on that issue for news about possible fixes.

The workaround in brief

1. Right-click on the image in the editor and select “View Selection Source”. (That is the name of the option in Firefox. Other browsers may word it differently.) You will see the HTML <img> element.
2. Find the src attribute.
• If the image comes from an external source, you will see a URL. That’s easy.
• If the image is attached to a Confluence page, the <src> attribute will look something like this: src="/download/attachments/181535157/1.png. The number in the middle, in this case 181535157, is the identifier of the page to which the image is attached.
3. Now construct a URL to view the page that contains the image, using the page ID instead of the page name: http://MY.CONFLUENCE.SITE/pages/viewpage.action?pageId=181535157.

A real example with pictures

In our release notes, we use a stylised number to illustrate the highlights of the release. The numbers are images, named 1.png, 2.png, and so on. We store them on a single page and reuse them in all the release notes.

Here I am editing the JIRA 4.4 release notes. I have right-clicked on the image that shows the number 1 in a grey circle:

Right-click on the image

Click “View Selection Source”, to see the HTML for the image element:

HTML for the image element

Grab the long number from the src attribute. In this case, it’s 181535157. That the identifier of the page to which the image is attached.

Construct a URL to view the page that contains the image, using the page ID instead of the page name, and use your magic number for the pageID: http://confluence.atlassian.com/pages/viewpage.action?pageId=181535157.

That URL takes you to the page called “_Images for Release Notes“, which is where we store the images for reuse in our release notes:

The page where the image is attached

Notice that you can get to a page via two URLs. One uses the page ID, the other uses the page name.

And voilà, you’ve found your image.

How to convert a bulleted list to a table in Confluence 4

This happens to me so often: I create a list on a Confluence page, and then discover that I need to add another layer of information to each item in the list. It should be a table! How can I convert it? Thank you Jay Rogers for discovering and sharing this tip.

In Confluence 4.0, to convert a bulleted list to a table:

1. Copy the list.
2. Paste into a Microsoft Excel spreadsheet. Excel will treat each bullet and line feed as a separate row.
3. Select and copy the cells in Excel.
4. Paste them into the Confluence editor. Voilà!

This trick works in Confluence 4.0, but not in Confluence 3.5. It works with Microsoft Excel, but not with a Google Docs spreadsheet, nor with a Zoho spreadsheet. It is worth trying with other spreadsheet applications, if you happen to have one lying around. Let us know what happens!

Here it is in pictures. Click the images to see an expanded screenshot. Here is a list in the Confluence 4.0 editor:

Bullets

Copy and paste into Excel, then select the cells in Excel:

Excel

Paste into the Confluence editor:

Table

How to search Confluence for usage of a macro

Do you need to find all pages on your Confluence site that use a given macro? You can do it via the Confluence search. Here’s how, in Confluence 4.0 and Confluence 3.5.

Confluence 4.0

Enter the following in the Confluence search box, assuming that your macro name is “x”:

macroName: x*

For example, let’s say that you want to search for all “include” macros:

macroName: include*

Or let’s say that you want to search for all “excerpt-include” macros:

macroName: excerpt-include*

Notes:

• The key word is case sensitive. It must be “macroName”, and not “macroname” or any other variation.
• There is a space between the colon and the macro name.
• The macro name (x, include, excerpt-include, and so on) is the value that you supply in wiki markup. (It is the name of the macro as defined in the “atlassian-plugin.xml” file.)
• The asterisk at the end of the macro name is required, to ensure that the search picks up all references. (Evidently the reason for this is that the value in the query is stemmed, but the value in the Lucene index is not stemmed. The asterisk will prevent the stemmer from kicking in.)

Searching for a macro in Confluence 4.0

Confluence 3.5

In Confluence 3.5, you can enter the curly brackets and the macro name surrounded by double quotation marks, like this:

“{excerpt-include”

Or this:

“{children”

Or even this, to find all occurrences of the include macro that include a given page:

“{include:my page name”

The trouble is that this will pick up all occurrences of the search term, both with and without the curly brackets.

As an alternative, try this plugin, which provides a user interface for a Confluence 3.5 macro search: The Macro Usage plugin. It is not (yet) compatible with Confluence 4.

Thank you

Thank you to Daniel Kjellin, the Confluence developer who wrote the Confluence 4.0 macro usage search, and who told me all about it! I just discovered it today. I hope you find it useful too.