Documentation:  Collaborate and Benefit

9/9/2012

0 Comments

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

1st July 2012

7/1/2012

2 Comments

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