That is The Week That Was
I was reading an article on Linkedin this weekend where someone said that they were having a horrible time using their wiki and that they wouldn't dream of using it for client-facing documentation. It isn't the first time that I've heard this argument: it is an argument that is completely spurious.

This sort of negativity arrises when lots of people are contributing but no one is managing: if you don't have someone (or several someones) organising and looking after your documentation, then yes it probably will become unusuable.

But when you dig into the argument you find that what you're probably suffering from is having LOTS of content - which is a good thing. You want lots of (or at least, the right) content (as it's got to be quality over quantity) and having lots shows that staff are contributing - which is definitely a major benefit. The only negative is that you don't have someone in charge of it.

Which is where a technical author comes in handy.

A technical author (or someone similar) will not only write your normal user info, but they can also edit the content supplied by other people. 

I do this all day long and am happy to do so. I've got my notifications set up so that I'm told every time someone edits one of the user content spaces. I can see at a glance if anything needs to be done and sort it out then and there. It's that easy.

One of the major benefits of using a wiki to deliver your client-facing content is that EVERYONE can contribute. That is EVERYONE from ALL depts in your organisation. And as long as you've got someone who's making sure the writing etc is up to scratch, corporate styles are followed, and that they're organising it properly, then what you have is MANY people creating content instead of only one or two or maybe even none.

So next time you hear this argument, don't focus the negative. Instead realise that this is actually a positive thing that is good for you all, it is an opportunity waiting to be grasped.

Tip of the Week
Have you tried using the Task List macro? If not, then give it a go. 

Although you can use it for your own work, it's great for teams too. It's great because there's a lovely little arrow that appears to the left of the task's details that allows you to assign the task to someone else in the team.

When you click on the arrow, see Figure 1, you can prioritise the task and assign it in seconds. When you do this the assignee is automatically notified of the task and it's priority. This means you can organise and
assign tasks quickly and easily, and know that the recipient is completely up to date with what you want them to do.
Cheers.
Picture
Figure 1.

 
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!
 
That Was The Week That Was
My main background task decided it no longer wanted to hide away in the shadows and instead burst out and took over my entire working week. I blame myself, but it was a long and repetitive task that I decided had to be finished asap - even if that meant hours and hours and hours of drudgery and repetition, replication and reiteration.

Still it could have been worse: I could have been using another tool: Confluence has a habit of making the dullest job rewarding.

Big Thanks!
I'd like to thank Andrew Frayling for his comment about how to make using shortcuts even faster and simpler in last week's blog. If you're a more advanced user, you'll find his blog fascinating and helpful.

Start Your Editor
I've talked a little in previous posts about writing and working within Confluence's editor, but I haven't really said much about the editing environment itself. So in this week's blog, I'll focus on some of it's functionality and the benefits it has for technical writers over more traditional tool such as MS Word.

The first has to be sheer ease of use, starting with opening the editor in the first place. If you're familiar with Confluence you'll know there's the big, hard-to-miss and very easy-to-click-on Edit button in the toolbar. Ignore it, it's not needed. You want to start 
editing? Just press the 'E' key and hey presto, you're there. 

I know, ridiculously simple and perhaps not worth all the song and a dance. But it is, because it demonstrates the detailed level of thinking Atlassian put in when they designed it. I.e., the user experience was upper most in their minds. This is very important because even now there are far too many software houses who forget to consider the user. I know this is true because I have to use such software on a daily basis. And I hate it.

So you've opened the editor and want to start writing, but you want to start by adding a heading on the page (as opposed to the page's heading). Which means formatting it. You could take the easy route and slide your mouse up to formatting the drop down list in the toolbar - but let's face it, your hands are already on the keyboard and your mouse is far, far away. In fact you know the whole operation of grabbing and using the mouse is very s  l  o  w. 

So why bother? Especially when you can create the heading you want just by typing it into the Editor? All you have to do is enter the heading code, press space and enter your title text. For example:
The heading's code uses the following elements:
  • h - always lower case.
  • 1 - this is the heading level, so you could also use h2, h3 etc.
  • a full stop - this has to be immediately after the number.
  • a space - this effectively tells Confluence that what you've just entered is markup that needs to be converted.
The moment you press the space bar, the 'h1.' code disappears, and when you enter your heading, it uses the built-in CSS formating for Heading 1. All gloriously simple and very fast.

And there are tons of other labour-saving, speed-inducing devices in the editor. For example:
  • for bullets, enter an asterisk at the start of the line and start typing.
  • for a numbered list, enter '1' at the start of the line and start typing.
If you want to insert a non-numbered line into a numbered list, all you have to to is, at the end of a line of numbered text, press Shift+Return. You can then enter a normal line of text. However, when you press Return, the next line will be a numbered line that follows on from the last one. If you don't want that to happen, the keep using Shift+Return until you do.

Better, Faster, Stronger
There are many things you can do in the editor ranging from adding links to internal and external pages, using graphics, charts and videos. The possiblities are almost endless: I'll talk about more of 
these in future blogs.

From Fact to Fiction
There now follows a shameless plug for my fiction writing...

I'm happy to tell you that my first novel, The Darkness Beneath, is now available as an eBook from Amazon (.com and .co.uk). It's a gothic tale of death and destruction in London's underground railway system. 

Written with more than a passing nod towards the best of the Hammer horror and vampire films, you can download it in seconds for the very modest sum of $1.99 right now.
Cheers.