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.
Successful Content EditingThis 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.
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.  Figure 1.
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 is The Week That Will Be
Short blog this week I'm afraid as I've a ferry to catch in a few hours. I can't wait though. When I haul myself into the office in Cambridge very early on Monday morning I'll be able to get my hands on a fully set up JIRA - which will be great as I intend to use it to track my technical writing and other documentation tasks (for example, the documentation I manage for other software we produce) in the Agile environment.
Not only that, but I'll be able to start investigating how JIRA and Confluence can interact with each other via the gift of macros. I'll also be up to my eyeballs in meetings about documentation and the way forward - i.e. how we can improve what we're already doing by using more of the inbuilt Confluence functionality.
On Tuesday I'll be on the train down to London to carry out some wiki training with the Marketing Dept, plus we're going to investigate ways of using Confluence to help them with their work. Finally I'm hoping we'll have time to look at how we can hook up our new website with the wiki. So it's very exciting times in terms of getting Confluence out in front of more people, and using it for more business-orientated tasks.
One of the drawbacks of using a wiki is that people tend to see it as just a place to store and find info - which what it is brilliant at. But it can be much more: how much more I hear you ask? Well, watch this space and we'll see.
And if all that excitment wasn't enough, I'll be carrying out ad-hoc training all over the office in Cambridge, plus the induction training for new staff in development, testing and support.
Expect a full report soon, just don't expect it to be next Sunday, as I'll be getting up at 04.30 to catch the 0800 ferry back!
Cheers.
That Was The WeekWell, 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 WeekA 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:
- Open the page in Edit mode.
- Put the cursor where you want to insert the macro.
- Insert an opening curly bracket ({).
- Now start typing the following letters: sea (the first three letters of the word 'search').
- When you do this, the options in the drop down list will change. One of these is Page Tree Search.
- 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 WeekAnother 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 WeekA 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
As this is my first blog about using Atlassian's Confluence wiki as a technical author, I think a short explantion is required.I've been working as a technical author for about 15 years, mainly in software but I've also worked in other areas such as hardware and OM document sets. My current role is with a British software house working in trading and risk management.Three years ago we started using a wiki for all our client documentation as well as our intranet. Last year we acquired two other companies, both of whom used Confluence. After comparing the two systems we were using, we decided to use Confluence throughout the entire organisation. That done, we migrated our original wiki along with the two other Confluence instances into one brand new one. A great deal of thanks for the success of this project have to go to Clearvision, an Atlassian partner, who organised and oversaw the whole operation.I firmly believe that Confluence is the way forward for technical documentation, and, having used wiki technology for three years now, I believe I have the experience and knowledge to back this up. I intend to do this in the coming months as I describe and share my experiences and insights gained.But First, This!Last Monday, the 12th March, I attended Atlassian's Unite conference in London. This not only gave me first hand access to various Atlassians, including Mike Cannon-Brookes (co-founder and CEO) but also to a huge number of people who are connected to Atlassian. They are connected because they are users like me, or are Atlassian partners. For example, Clearvision and Adaptavist.The morning kicked off with a talk by Mike Cannon-Brookes that covered everything from it being Atlassian's 10th birthday (almost) to sending out their very first invoice, to where their tools are now and where they are heading. After that we got further insights from other Atlassians into Confluence and JIRA, which in my eyes are the core Atlassian products. What I really enjoyed about all this was the refreshingly straightforward way the company presents itself. It might be that they put their best face forward, but there is no BS here - something a lot of other businesses would do well to emulate.Lunch looked excellent but I forsook the very long queue for it for a small salad. On the upside I managed to get myself a place at Mike's table (Atlassian had several tables manned by staff who were there to spit out advice and information between mouthfulls of lunch). Our conversation ranged from the enormous size of Australia, to the un-helpfullness of the weather, to promoting the use of Atlassian products to colleagues and senior management. It was refreshing to hear a CEO straight-talking instead of spinning and weaving.The afternoon continued with a couple more talks about JIRA and building the Atlassian community in the UK, featured demos from a variety of clients that covered how they used Atlassian's products in their production systems, and gave insights into how they promoted the use of the technology to staff. This is something I'm keen to know more about as part of my role is to be the wiki evangelist, and although most people see the benefits as soon as they start using the software, there are a few you have to use velvet thumbscrews on.Also, you might expect these talks to be primarily from software and technology businesses, which is true, but in fact manufacturing industries also use Atlassian's products. For example, we were treated to a lively talk from the world's second largest pump manufacturer in the shape of Ole Kristensen, the lead consultant at Grundfos.The day ended with everyone hot-footing it to a nearby bar for refreshments and even more conversation, free food and business card collecting. Which demonstrates another thing Atlassian is very good at: community building - which is almost the primary function of all their products. Obviously, on such an occasion, you can't talk to everybody, but you can target a few people and build more personal relationships with them. For instance, I built on my existing relationship with Clearvision and various members of Atlassian's support teams, and launched a new one with Adaptavist. This resulted in getting some very heplful insights into using their Community Bubbles plugin, (which we're using to build our client forum) plus the promise of some free support when I start setting it up.All in all it was an excellent day and money well spent: I went home full of useful information, fired up with the knowledge I'd gained, and very pleased with the opportunities for various collaborations that had arrisen during the day and evening.Now all I have to do is write up my nine pages of notes for my management report, fill in my expenses claim, and get the forum set up and working: life as a technical author will never be dull again.And Now For Something Completely DifferentAs of next week, my blog will focus more on how I use Confluence for technical writing and related matters. This means promoting the wiki and its usage to colleagues, technological issues, developing the wiki (structurally and functionally) support issues etc etc. Please feel free to comment and share your thoughts and ideas.
|
RSS Feed