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 Was The Week That WasMy 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.
|
RSS Feed