Davidson Media

Yeehaw, what a week it's been! Confluence 4.3 launched - can't wait to get hold of that for the updated tables functionality alone - and more Jira training than you can stuff into a Mary Poppins bag.

Now that we've got Jira rolled out through the entire company, I'm looking forward to seeing how I can use it with both Confluence and my technical writing. I'm wondering just how much benefit there'll be from using the Jira macros in the wiki, and how these allow the two system to collaborate.

More on this as and when.

More Work, More BenefitsAs a technical writer I'm used to researching, writing and publishing user guides. In the pre-wiki days this was a relatively straightforward process involving MS Word, graphics, tables, reviews and PDFs.

In a wiki it's more complicated: there's more to do. Despite this, I still believe wikis are the way forward for a lot of user documentation.

Although my writing processes still encompasses the steps listed above (minus using Word - now I either write directly into the wiki or I write in Notepad), it also includes a number of other things such as:

And there's more. For example, I now have to monitor work from other depts that they've added to the user info. I have to research the tools (macros and plugins for example) available because I want to see if we can use these to improve what we're delivering and how we deliver it. Although we don't mess around with the content and formatting just because we can, we also have to test new ideas out to see what benefits these bring.

All of this adds work and yes, it does make the whole process of creating and delivering user content longer and more complicated.

But the benefits to myself as a techcial writer, and the company and clients in terms of better and more usable content far out way the negatives.

It's an investment in time and effort that rewards everyone - and you can't say fairer than that can you?Cheers.

Another working week has flown by and sadly it was a forum-free week: my time was devoted to more urgent tasks, such as writing a How-To guide on setting up and using blogs.

Not that I mind giving people more info on how to make better use of Confluence, but sometimes when you really want to crack on with a project, it becomes a project that is destined to slip out your grasp.

Ultimately that won't happen with the forum, because I'm determined not to let go of it until it's working and being used by clients.

Shortcuts and MacrosOne of the jobs I've been doing as a background task for the last few weeks has been to convert the contents of a spreadsheet into a series of wiki pages.

This equates to seven columns of data for each row, and several hundred rows, all of which have to be split into separate pages. Each page contains one or more table depending on the type of info. And while all of these are separate pages (99 in total), they all have to be grouped into one page so that they can be searched en-masse and printed as a PDF.

The process for doing this is easier than you think, thanks to some helpful built-in functionality, aka, macros.

Although adding all the data from the spreadsheet is laborious and time-consuming, once you've added them, the process of grouping them onto one page is very easy. All you have to do is insert a macro into the page you've created to group the content on, choose the page you want to include, then saving the macro and the page. The whole process takes about a minute normally.

To do this you can use another one of Confluence's brilliant shortcuts. In this case the shortcut is the left facing curly bracket.

Another example of a shortcut is pressing the 'E' key to open the current page in edit mode. Brilliant! It's this sort of thing turns Confluence into the Swiss Army Knife of technical documentation.

When you're in Edit mode, enter a '{' and the Macro suggestions window opens, see Figure 1. Next press the Up arrow key to select the Open Macro Browser option, and press Return.

Now start typing the letters 'I, N, C' (you can use lower case, these are capitalised for clarity) in the search box. Bear in mind that you don't even have to click in the search box as the cursor's already there (yep, even more labour saved).

When you do this, the number of macros displayed is reduced to only those whose name contains the letters you enter.

The next step is to select the appropriate macro and enter the only parameter it needs, the page's name.

Figure 2 shows the Include Page macro, while Figure 3 shows the parameter I've entered in the Page to include field. All you have to do now is press Insert to close the macro window, and then save the page.

When you do this, the macro automatically gets the content of the parameter page and displays it on the page you've just saved. To add all the other pages you need using a seperate Include Page macro for each one.

The contents of the group page are automatically refreshed whenever you open it, so if the content of the parameter page is edited, it is the new content that is displayed.

But wait, I hear you say, what if I want to include a page that is in another space, is that possible? Providing you have permission to view that page, then yes it is possible - and not only that, Confluence makes it easy for you to do so.

Spaced InWhen you start typing in the Page to include field, after you've entered two or more letters a list appears based on those letters, see Figure 4.

The list contains pages with that name from all the spaces you can see. If you run the mouse over the options, the name of the space appears, see Figure 5.

All you have to do is select the appropriate option, press Insert and save the page. The parameter you select has both the space's key and the page's name, for example - spacekey:pagename.

I'm not sure if there's a limit on the amount of Include Page macros you can use on one page, but I've used 67 so far one page and it still works exactly as expected. In most cases you won't need to use so many (and if you do stand by for some te-di-um) and the benefits are well worth the effort.

For a start you'll have all the info in one place, which makes it very easy to create a PDF (in two clicks) with all the content from all the included pages. For searching, you'll have all individual pages which can all appear as separate results. And you'll have one page with all the appropriate info which you can search using your browser's built in functionality.Details and BenefitsWhat I like about the ease of use we get with the shortcuts and macros is the attention to detail they show. Both demonstrate how much thought Atlassian put into their products, thought that all Confluence users can benefit from.

About the Blog

Hello and welcome to my blog on using wikis for technical authoring. Published weekly, it focuses on my experiences using Atlassian's Confluence wiki, though I may get sidetracked. I've been using Confluence for over ten months now, so the information and tips you'll read here are for those who have little or no experience of it. I've been using wikis for technical documentation for three years.These are my personal opinions: I am not connected to Atlassian in any way other than using their products.Feel free to comment and share your ideas.What's a Wiki?A wiki is a web-based knowledge base populated with content that can be text, graphics, charts, videos etc. One of is key features is that it allows users to collaborate on tasks such as technical writing and development projects.

LinksYou can find more Atlassian experts and products by following these links.