17th June 2012

6/17/2012

0 Comments

 
That Was The Week
Well, after a little waiting around and re-organising to allow everyone to be present when the upgrade was carried out, we finally moved up to 4.2 this week. And it was definitley worth doing and worth the wait. Fortunately for me, I had an enormous pile of writing to do in the pause, so getting bored wasn't an ordeal I faced.
Really Neat and Useful Tools
There are many great new features and enhancements in 4.2 but I'll only describe a couple of them here. For a list of features see: Full Features List 180 features. Take my advice, do this when you won't be disturbed. And pack plenty of food and drink - you may be some time.

One of the useful things is the Search and Replace - which is a really useful tool for those of use who are constantly chiselling content out of the coalface of rapidly evolving technology. I can't remember how many times I've needed this functionality when trying to update a word that's been changed in development and now has disseminated to all four corners of the wiki.

This doesn't need much explaining: it does what it says on the label. 

To run this function press Ctrl+F in the Editor to enable the dedicated toolbar. Once there, you enter the word you're looking for, then use the Previous and Next buttons to search for your word. When one is found it's highlighted in yellow. You can replace words individually or en-masse using Replace All. With this, you'll see a message appearing in the bottom right of the screen saying how many replacements were made.

Another neat bit of new functionality is Page Layout, which you can use to impose a basic layout on an ordinary page. Again, you can only access this in Edit Mode. When you're running the Editor, the button sits to the right of the Insert icon. Here you can find ten different layouts - think of them as a framework - including none, which is handy if you want to get rid of any layouts already added. But have no fear, while 
this removes the layout framework, your content remains intact. Phew!

By choosing any of the options you can divide a page into areas that you can add content and other macros to. For example you could have a simple two or three column structure. But you could use something far more complex, such as a multi-column structure with a sidebar. This means you can organise a page into discrete areas, rather than having all the separate content elements mixed in together.

There are two levels of layout: simple and complex. The simple versions are as you'd expect, but the complex ones also have a row above and below the columns. 


For example, imagine using a complex option of two columns with the two extra rows top and bottom. These could be used in the following way:
  • The two columns could contain a list of data each.
  • The top row could contain an explanation of the purpose of the data.
  • The bottom row could contain notes on specific elements of the data itself. 

Obviously this is a very simple example, but I think it shows how you can, with very little effort, add structure to a page that would make it easier for users to understand and assimilate what they're looking at.

So there you have it, a couple more ways Atlassian are hell bent on making the life of a technical writer easier, faster and yes, even more glamorous.

Tip of the Week
A brief look at one of Confluence's many functions.

Name: Page Tree Search
Available from: Insert/Other Macros; directly from the Editor.

One of the problems with being able to search all the data in your wiki is the number of results you get. Confluence has a number of ways of narrowing this down but one of my favourites is the Search Tree macro. 

This only searches the page you're on and it's subpages. This means the results for the term you're searching on are limited to only a handful of pages. This can be used on any page because it's a macro that you can add yourself, wherever you want it.

To do this:
  1. Open the page in Edit mode.
  2. Put the cursor where you want to insert the macro.
  3. Insert an opening curly bracket ({).
  4. Now start typing the following letters: sea (the first three letters of the word 'search').
  5. When you do this, the options in the drop down list will change. One of these is Page Tree Search.
  6. Select that and then user Ctrl+S to save the page.

When the page has rendered you will see the search field and the Search button. 
Happy hunting!
0 Comments

Simple, Quick and Easy to Use

4/1/2012

4 Comments

 
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 Macros
One 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 In
When 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 Benefits
What 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.
4 Comments