This week I want to give a quick demo of how collaborating with colleagues on a project actually works in Confluence, and describe some of the ways business benefits from this.

This won't take long and will cause no pain: in fact you may even find your 'Happiness' button being pushed.


Collaboration: Last but not Least
Over the last couple of years our business has aquired several other companies who had their own documentation and documentation systems. These are spread around Europe and Scandanavia. To complicate matters further, we have several other offices around the world. Fortunately the wiki is used a central point of reference, a meeting point if you will, by us all.

Several people, myself included, wanted to do something to bring all the documentation from the various departments and offices together. We wanted to coordinate not only the docs themselves, but their styles and formats, processes and deliverables. We also wanted to see where our strengths and weaknesses were, and see how we can use this info to improve our client-facing and internal documentation.

To do this we formed a new group and started a new space within the wiki called Global Documentation. We then invited as many people to join the group as we could think of. Naturally not everyone invited has the time or inclination to do the work, and those who wanted to were able opt out, did but many are still part of the group.

There are three main movers in this group (naturally I'm one), with other members adding their feedback and thoughts on a variety of subjects whenever the need arises. For example: versioning the user info. 

One person started this converstion with me, and I added it as a topic to the Global Docs space. Using the @mentions functionality to target those I knew were responsible for user documentation, I asked the group for feedback on how they version their info.

Quick 
How-To On Using @mentions
To use @mentions, all you do is add the '@' symbol and then start entering the persons name. A list will appear that auto-populates as you type. When you save the page or comment, the persons you targeted is automatically sent a notification. It's that simple.

Back To The Future OF Documentation
They were notified as soon as I saved the page and within a matter of minutes a few had added their own updates. So with very little effort, a a globally-based conversation had started. Now every time someone updates these pages, everyone involved gets notified.

Because the notifications include the updates, they can see how the conversation is going without having to go to the wiki. Even better, they can reply to updates really easily using the built in Reply option. 

This means:
  • people are getting involved in a way they wouldn't have before.
  • because people are talking to each other, we're discovering more about how the company works, and where we can improve this.
  • conversations are happening in one place.
  • the conversation is not getting lost, spread out and dissipated in multiple emails.
  • no one is being accidentally left out.
  • the whole conversation can be found and searched by anyone with access to the space. (And this space is open to the entire company as we believe everyone should have the opportunity to take part, even though their involvement may be limited to being a watcher.)

On top of this there are some more subtle benefits, such as using the Like button to show that you've read something even if you can't reply to it immediately. I do this because, and this is really helpful if you're targetting a specific person, it lets the other person know that you've at least read what they said.


This probably isn't what Atlassian were thinking of when they built this functionality into Confluence, but it suits our needs to use it this way.

From all of this you can see how, on a global level, geography and time are not an issue. People all around the planet are connecting, conversing and collaborating without little effort.

The business benefits are many pretty obvious: in my opinion if you're not using this sort of technology, then you are actually missing the opportunity to get people involved and working together without a song and dance. 

Is this something you can afford not to do? 

Cheers.
 
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 Benefits 
As 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:
  • adding labels/tags (for searching and grouping)
  • adding links (to and from related topics)
  • using a wide variety of macros (to re-use content, create TOCs, searchable fields etc etc).

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.
 
Hyper-Hyperlinks - Connecting Content
One of the great things about using Confluence for technical writing is that you can connect related topics using hyperlinks. 

These allows users to see these connections and navigate through your documentation in a logical way - and they're super-easy to create.

In fact this underlines one of the main advantages of having your content in a wiki: everything can be joined up. Although other documentation systems allow you to do this, the wiki makes it ridiculously easy to do so.

Not only that, you can find the links to any page really, really easily. In fact, you can do that in two clicks. See last week's blog for more info on how you can do this.

To add a link, all you have to do is select a word, then use Ctrl+K to open the Insert Link window.

From here you can:
  1. run a search for the appropriate page
  2. select from a list of recently viewed pages
  3. select and attachment
  4. insert a web link (URL)
  5. use the Advanced settings.

Although I use the first and fourth ones a lot, my favourite is the recently viewed pages option. This is simply because it's almost inevitable that I would have just been looking at the page I'm going to link to (to check it's the right page of course). 

As this page is normally at the top of the list, all I have to do is select it and press Insert. So with the very little effort that is required to click the mouse three times, I've created a link and can get on with something else.

Now then technical writers, the question is, how much easier can this get?
Cheers.
 
Successful Content Editing
This week I want to alert you to a little piece of Confluence functionality that does an awful lot of work. This is the info page, which you can find under the Tools menu.

This contains a lot of data about the page, for example its history, who's been editing it, when it was edited and its position in the hierarchy.

But by far the most important element for technical writers or other engaged in collaborative documentation are the two lists of links: incoming and outgoing. 
See the graphics at the bottom of the blog for examples.

These are incredibly useful as they allow you to see:
  • the pages are that referencing the page you have open
  • the pages the current page is linked to.

This means you can see what the related pages are. You can then jump to these pages to see if the edits on Page A affect anything on Page B. If so, you can edit it straight away. So, right here, right now.

By using the Info page, you have a much better chance of making sure that all the content of all the related pages is updated because you can easily find the connections.

Of course, it still pays to do a search for related content, but using the Info page will help reduce the amount of time spent on this. It also cuts out a lot of the uncertainty we have about knowing whether we, as technical authors and collaborators, have covered all the bases.
Cheers. 

 
Collaborate and Win, Win, Win
One of the reasons I believe wikis are the future of documentation is their ability to be collaborative. But what does collaboration mean in technical documentation and for technical writers?

At a basic level it's simply the ability for several people to work together on one document or set of documents. 


Ok, that's not exclusive territory, there's plenty of tools out there that will do that. But in my opion there is a big difference between those sorts of systems and a wiki. The collaborative advantage wikis have I'm talking about is that people are more likely to contribute new documentation and ideas.

For example, in the last few weeks we've had new user documentation added by both the development dept and consultants. In fact the content from the consultants started out as a 90 page Word doc which they then re-wrote for the wiki. That's right 90 pages of free, at-the-coal-face technical writing that I would have done, as a lone technical writer, 'some time in the future.' Which means at any time in the future, or not at all.

Another example are the minor updates the Support dept frequently makes to the user information. They not only update the content but expand it as well. Which helps our clients and internal users alike.

This 'many hand makes light work' approach brings several benefits to both the company and clients, for instance:
  1. The quality of client facing info is improving all the time.
  2. As the technical author, I can focus on writing new development etc.
  3. Staff feel empowered to make changes and suggest ideas. 
An example of the latter is that people have ideas for content they'd like to see on the wiki. Because they know we're always looking for new content, they now suggest new topics and will either write a rough draft which I can then re-shape into user information, or they will supply the background information for me to work from. They will also review and correct it before publication. Before the wiki these ideas would have been still-born.

On a more global scale, in a multi-national company such as ours, exposing all our docs internally means our offices around the world can see what the other are producing. This has helped us to see where we can make improvements and to unify both our processes and the look of all our documentation.

So using a wiki has not only helped remove data silos, but because people feel empowered, they are motivated to both suggest new ideas and to improve quality.


All these things provide a much more positive and collaborative mindset which benefits colleagues, the employer and clients. It's a win win win situation, which is not something you can say about a lot of other systems is it?
Cheers.
 
That is The Week That Was
I'm back home after a week-long stay in the UK where I spent a great deal of my time training people on using Confluence and more talking to even more people about how they can use it to enhance their productivity and ability to collaborate with others.

We've recently taken on a bunch of new people, ranging from developers and testers to admin and marketing staff - all of whom have different learning and business needs. I give them all exactly the same training (though the levels we go in to and the speed of delivery varies).


It's remarkable that one tool can be used by so many different departments with different goals etc. But then again, perhaps it isn't. 

It's all about creating content: what that content is, it doesn't really matter, the tools are the same even if the desired outcomes are not.


All Wiki Usage Is Not The Same
Many people see a wiki as a knowledge base, and a great place for creating alls sorts of collaborative documentation - and I don't just mean technical writing - which is true of course. But it's also a great place for working in too.

For example, I've created my own personal space in the wiki and set its permissions up so that it's totally private. This means that I can write what I like and no one else can see it. Which gives me the freedom to not worry about how a page looks or to be too concerned about using full-on writing skills. (Do you know how much pressure a writer is under when they send out emails etc? Because not only is the smallest mistakes lept on by colleagues ever anxious to pull your leg, but when you see a mistake yourself, you feel like you're looking at a huge flashing neon sign that screams "The Tech Writer is Crap!" at the world.)

It also keeps everything you write out of the reach of the search engine. And although you colleagues will never thank you for this, it does mean that you can be quietly satisfied that you are, in a very small way, helping the company run slightly more efficiently.

Your personal space can be used in the same way as any other space is. 

So all the editing, the search and the plugins can all be used to do anything you want. You can even create your own templates, which you can either make available to the whole wiki, or keep hidden in your own space.


Agile, Step By Step
We've recently started using the Agile development process and because of this, I'm now getting lots of small bits of info to work on. These will develop through the sprints and eventually be reviewed and published in the user information space. Because I do all this in my own space, I can organise it how I feel (as opposed to structuring it to fit the current content), add links to related info, make notes to myself, and chuck in ragged graphics. I can also add questions to the text that I'll either answer as I find out more through the Agile process, or I'll ask colleagues about if I get stuck. So nothing's missed and everything can be included and I don't have to worry about the formatting until I'm happy with the text.

Because of this, I can refine the content until all the questions have been answered and removed and I'm left with content that can be published to clients. The benefit of all this is that the work is never publicly available until I publish it - so I don't have to worry about rough drafts and misinformation being found and used by others. 

In A Wiki, Everyone's A Collaborator
Which means every one else can do the same - even those who are reluctant writers, people who are afraid that they can't write or have problems with grammar and spelling. Of course, if they do want to publish their content, then they'd be wise to get their friendly technical writer in to give it the once over. And that's what colleagues do, I'm glad to say. 

While I'd be the first to admit that there isn't a tidal wave of new content from other non-writers, there is definitely a ripple (the ripple being the amount of small edits that people do to correct the accuracy of the content, or the queries they present the tech docs and other departments with and the pages of new content they are adding). This is partly helped because everyone knows that the tech docs dept is keeping an eye on client content and will double-check everything that's published there, and partly because they're getting more and more confident about publishing to public spaces. As they see the benefits of collaborating (though some would recoil at that word: contributing might be a better one), and how easy it is to do, it becomes the most sensible thing to do.

And this benefits us all, as there's no way one person can write everything that could be written as far as the user info is concerned. 

Now instead of having one technical writer trying to do everything, more content is being produced because other people see a gap, know that they've already got a load of notes in their private space, and start turning them into something that can be used by us all. 

The beauty of this is two fold: firstly what they write about isn't limited to user content alone, it can be anything at all; and secondly, because people get used to adding notes etc to the wiki that they know could be useful to other people, they stop pouring it into the secret silos that lurk inside every PC and laptop. And that is a very good thing for any organisation of any size, in any field of business.
Cheers.
 
That Was The Week
And what a good one it was, largely because we had the Dutch Atlassian User Group meeting, which is populated by lots of really great people full of useful information, and all willing to do what they can to help
those who arrive with a laptop full of questions.

One of the great things about using products you are genuinely enthusiastic about, is that you meet other people who feel the same, which means meetings like this are not something you do 'because you have to'. Just the opposite in fact. And I couldn't say that about many products I use from any sphere of life.

Aside from talking to many of the Atlassian experts and partners, we also have case studies from people who are using one or more of Atlassian's products. This means you also get an insight into using such things as JIRA and Greenhopper for example. You also find out more about how people are using the same products in different ways.

One of the best things for me is those little bits of info that you come across almost by accident. We had one of those this week with an impromptu demo of Confluence 4.3, given by Stefan Kohler, who is a developer and scrum-master of Atlassian partner 42.

His demo came right at the end after the big screen was packed up and featured @mentions (see earlier blogs) combined with the Task List functionality.

The latter has been updated to make it easier and faster to use, and allows you to assign tasks to people using @mentions. When you do this, the person mentioned is sent a notification which is highlighted in the toolbar next to their user name. This means they can easily see that someone's sent them a notification or assigned a task to them.

When you recieve a notification you see an envelope icon by your name. If you click on this, you can read the update and react to it by writing back using the same message. So without having to go anywhere else, you can message the sender back. All of which makes the functionality simple, fast and efficient - and totally brilliant. And I can't wait to get my hands on it.
Cheers.
 
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
Another fairly quiet wiki week as I've been doing on a lot of writing for the latest release, as well as preparing for the next using the info coming from the Agile meetings.

We're still inching towards 4.2: I think that should be with us this coming week. To that end I've been studying all the changes Atlassian have made and have set up a page listing the updates and who should be interested in what changes. 


I'm not trying to dictate to our users who can use what - in fact everyone can see the full list, so can look at what they want. What I've done is to suggest which departments the changes affect the most, and the updates that will be of most interest too them. In other words, to supply a level of focus so that people can see what's most important to them, rather than wading through a list playing spot-the-benefit. 

I find that making a person's ability to use Confluence easier is the best way to get them to become more active within the wiki.

While I was looking through the updates, I came across an enormous list of functions that are either already available in the current version, or will be with 4.2. 

Although I like to think of myself as a fairly experienced user, there's clearly a lot that I wasn't aware of. Which is great: now there's even more to play with. BTW, if you're reading this and you're my boss, I mean 'there's even more functionality that will help make me even more productive.'

This list is called the 'Full Features List 180 features.' And comes with this helpful advice: Get comfortable.


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

Name: Status Macro
Available from: Insert/Other Macros

Have you seen the coloured Status macro that you can use to label a page's content? They come in four colours (grey, red, yellow and green) so you can use them to show an easy-to-see view of, for example, a task's status. You can add your own custom caption too. So you could use red to mean 'on hold', yellow for 'on going' and green to mean 'finished'.


You can also use them to help organise your tasks in your own way. For example, I might have finished a piece of writing that's been sent for review. To save me having to trawl all the words on a page looking for its current status, I could add a yellow label at the top of the page saying 'Sent for review'. Which means I'll be able to see the page's status almost as quickly as it can load.

I'm not sure if there's maximum number of characters you can use as I gave up counting at 100. That's not very practical as you can't use line breaks, which means it extends across the page without breaking.


Which isn't very handy, but I suspect that Atlassian didn't design it with that in mind.
Cheers
 
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.