Technical Writing: Faster, Smarter

8/26/2012

0 Comments

 
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.
0 Comments

Technical Writing Made Easy

8/19/2012

2 Comments

 
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. 
2 Comments

Collaborate and Win

8/12/2012

0 Comments

 
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.
0 Comments