Sharing, Collaborating: Reaping the Rewards

4/29/2012

0 Comments

 
That Was The Week That Was
Earlier this year my employer bought two companies who are also in the trading arena. One's based in Norway and Scotland, and the other's in Switzerland. This means we have even more wiki users to cater for and bring together. 

One of the problems any organisation faces when it's spread around the globe is creating unity. What can we do to bring people together so that we're connected?

The answer is, of course, the wiki: home of sharing and collaboration. 

But you knew I'd say that. But it isn't so simple is it? 

Well, no. You have to get people involved and the only way to do that is to show how it benefits them. And how do you do that when there's 400 people working in offices as far apart as the USA, the UK and Singapore? Good question: it's not going to be easy, but I have a cunning plan.

But First, This!
When pages are edited one of the things that has to happen is that anyone who's interested in the page should be notified of the change. This is easy enough if they were the page's creator or if they're someone who's edited the page already - they get updated automatically. As does anyone who's been added to the page as a Watcher.

But what about clients, how do they find out? Well it's very easy, all you have to do is add the Recently Updated macro to the home page of the space you want to take the data from, set up a couple of parameters - such as the way you want results displayed and the number of results shown, and press Save. Bingo! Finished.

Every time the page is opened or refreshed the list updates automatically. By having this on our user information's home page, anyone who opens it can see not only the most recent updates, but who made them and when. These are all shown as links, and there's a link to the page itself so users can jump directly to it. Which is very handy if it's of particular interest to them. 

And it saves me bags of time too: in our previous wiki I had to add all this data manually, so I've saved myself as much as 30 mins or more per day just by using one simple macro that takes about two minutes to set up (and forget).

Share and Collaborate
With something like eight different parts of the company producing a wide variety of documentation (everything from user info to sales and marketing) one of our challenges is making sure we're all using the corporate ID etc, but there's something else that's just as important: knowledge sharing.

And knowledge can be anything from the sort of docs each office produces to the tools we use. So what can we do about sharing our knowledge, skills and experience? Where can we keep it and how to make sure everyone who's involved knows where they can find this info AND stay in the conversation loop?

There's only one place of course: our very own wiki home; the Global Documentation space. 

At the moment this has very little info but it has it's own blog already (which is automatically included when you create a new space), plus a couple of other pages listing the team members and their 
details, including their areas of knowledge and skills.

Over the next few days I intend to add some info about what our office produces and how, and once that's done I'll be adding all the documentalists as Watchers (Tools/Manage Watchers) so they'll all be updated when I publicise the space to them (by editing the home page, which will have a welcome message and explanation about what the space is for). 

Once that's done, we will run all our conversations through the wiki and not use email. That way everyone will be kept up to date with everything as it happens, and all the conversations, content updates and comments will be in one easy-to-search space, and nothing will be lost or duplicated.

And once we've had that up and running for a couple of months, I intend to demo it to other departments and show them how, with very little effort, they can achieve the same thing and enjoy the benefits of sharing and collaborating.

You can find out more about wiki collaboration by clicking here.
0 Comments

Seminars and Shortcuts

4/15/2012

2 Comments

 
That Was The Week That Was
If you've been following my progress using the page includes macro you'll be delighted to know that this is now live to clients and working very well.

As usual some of my week was spent looking after other user's and helping them with their problems. Not that there are many: yes things do go wrong from time to time but I can't fault Atlassian's responses and help when problems arrise. Most of the issues I deal with are quite simply and easily resolved, for example:
  • people forgetting their log on details
  • people wanting help with a task, for example, moving page.
  • people finding something that needs fixing but they are unsure how go go about it.
Of course I have to police any content changes in the client areas, but given that I can review all changes from within the email notifications I recieve, this doesn't take very long. That said, the more content we have and the more people we have editing and contributing it, the more notifications I recieve. This is something you have to keep on the ball with, and I review every notification as it arrives. 

Time consuming? Yes. Pain in the backside? At times, sure, but if you don't do it you run the risk of something being published that you just might wish hadn't. So far, and because clients and colleagues are professionals, this hasn't been an issue.

Confluence for Technical Documentation
This week also featured a very informative one hour webinar entitled Confluence as a Platform for Tech 
Docs which was presented by, among others, Sarah Maddox, one of Atassian's technical writers and author of Confluence, Tech Comm, Chocolate. I was fortunate with the timing of this as it started at 1700 CEST, which meant the Australia participants were up well past their bedtimes and those in the USA had an early start.

Shortcuts - The Film
I recently described using shortcuts to speed up actions and production, but I think this could benefit from seeing this in action. 

Now thanks to the power of Jing, you can do that very thing by clicking here.
2 Comments

Speed Tricks and Shortcuts

4/9/2012

1 Comment

 
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.
1 Comment

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