Blog Archives

Recording of webinar about Confluence wiki, collaboration and technical communication

Yesterday I presented a Scriptorium webcast titled “Collaboration: A hands-on demo using Confluence wiki“. The kind folks at Scriptorium have made a recording of the webinar available, and I’ve uploaded my slides too.

This presentation is about collaboration and what it means to technical communicators, and how we can use a wiki to enhance the experience. I give a hands-on demonstration of creating a technical documentation space on a wiki. You will see how to design a home page using the Confluence editor, macros, and even a touch of Twitter integration. You’ll also see how to draft a page, invite subject matter experts to review the page, and keep track of what they do to your documentation. After walking through the simple workflow of draft, review and publication, I discuss the use of add-ons and plugins to supply more sophisticated workflow functionality.

It was great to get some questions from attendees and answer them at the end of the session too. Having a live wiki up and running was very useful to illustrate the answers!

Webinar recording

Scriptorium has published the recording of the webinar on SlideShare: Webinar: Collaboration: A hands-on demo using Confluence wiki

Slides with speaker’s notes

Once you’ve watched the webinar, you may find it useful to see the slides with my speaker’s notes. The slide deck includes screenshots of the parts of the demo that were live on the wiki during the presentation. The slides available on SlideShare: Slides: Collaboration: A hands-on demo using Confluence wiki.

To see the speaker’s notes, click the tab labelled “Notes on slide n” under each slide (next to the comments tab).

Who is Donna Dark?

Donna is a denizen of my demo wiki. She’s a technical communicator extraordinaire. Take a peak at the webinar recording. You’re bound to bump into her.

New guide to developing technical documentation on a wiki

We’ve just published a new set of documents in our wiki’s user guide: Developing Technical Documentation on Confluence Wiki. We started writing the guide during our recent doc sprint. Since then, I’ve put it through a technical review and added some bits. Now it’s part of the “official” documentation. That’s a doc sprint win. :)

Designing and developing this suite of documents was a lot of fun and very interesting. The project serendipitously combined a number of aims, all rather different in nature:

  • Think up something to do in the doc sprint.
  • Involve other doc sprinters in the project, especially people from outside the company.
  • Spike a “use-case focused” guide and make sure the result is useful even though it’s a spike.
  • Tie together all the information we have in various spots, about writing technical documentation in a wiki.
  • Put the guide into the core Confluence documentation, so that it will be maintained and updated from now onwards.

People who worked on the guide during the doc sprint

A number of people collaborated on this guide. Two were Atlassians and the rest were people who joined the doc sprint in November:

…and others who reviewed the pages, working remotely in various spots around the world.

What is a “use-case focused” guide?

One of the things we’d like to do is to provide more “use-case focused” documentation. By that we mean that the guides should focus on a specific use of the product. A better term might be “domain-focused” documentation. For example, for Confluence we should write documentation about how to use Confluence as an intranet, how to use Confluence as a knowledge base, how to use Confluence for technical documentation, and so on.

This suite of documents is the first stab at such a user guide.

Design of the guide

These are the principles on which the guide is based. It’s just a spike, so we didn’t hit all these goals. But it’s a very good start.

Write topics that are task-focused on the macro level. The words “on the macro level” are very important in this context. It’s a well-known principle of technical documentation that guides should be task-focused, as opposed to feature-focused. We tell users how to do the things they need to do, rather than documenting the features of the product. At the moment, much of our documentation is nicely task-focused on the micro level: How to add a space, add a page, add a comment, set page restrictions, and so on. But it’s not task-focused on the macro level: How to set up a space for technical documentation; how to push a document through the draft/review/publish workflow (using page restrictions); and so on. One good way of addressing this problem is to produce use-case focused (or domain-focused) guides.

Tell people only what they need to know. Focus on the aspects of Confluence that the target users (technical writers, in this case) need. Ignore the other aspects. For example, on a typical technical documentation wiki it’s not important to know how to follow users or use the other “networking” features of the wiki.

Employ progressive elaboration. Progressively reduce the level of detail in the step-by-step instructions, while increasing the complexity of the concepts. Start with fairly detailed instructions for the basic functionality, in the first section of the guide. Become less detailed in later pages, because the users will have become more familiar with Confluence. At the same time, they will be dealing with more complex topics. But that’s OK, because they’re in their field of expertise (domain).

Encourage users to explore the product and learn from the UI, rather than telling them exactly how to do every single thing. If a user guide is very comprehensive, it gives the impression that it documents the entire product. If something isn’t in the docs, people will think it’s not in the product either. They won’t try to explore the product. We should encourage people to trust the UI. Also, if a user guide is very dense, people won’t find what they need in it.

Employ content re-use. Use Confluence’s {include} macro to pull in content from existing pages, so that we can avoid duplicating content and can thus reduce maintenance.

The result

I’m delighted with the resulting guide: Developing Technical Documentation on Confluence Wiki. It’s not perfect, but it’s a very usable and useful piece of documentation and it certainly fills a gap. Thank you again to all those who took part in developing this guide, and to everyone who took part in the doc sprint!

Sydney Red Gum tree

A magnificent Sydney Red Gum tree I encountered on my walk this morning. Shot taken from a rocky ledge half way up the height of the tree.

Calling technical writers to join our doc sprint

We’re holding a doc sprint to develop some quick-start guides for Confluence wiki, JIRA bug tracker and other Atlassian applications. Would you like to join us? Write some real documentation on a wiki. Claim a limited-edition T-shirt and win your place in our Hall of Fame. Chocolate is inevitable.

We held our first doc sprint, similar to a book sprint, in February this year. It was a lot of fun. A number of stout-hearted community developers took part, as well as the Atlassians brave and true. For that sprint, we concentrated on developer documentation. I blogged about the results and the planning.

Calling all technical writers to join our doc sprint

Nothing to do with doc sprints. I just liked this tree. Spotted in Manly Dam park.

This time our focus is on quick-start guides for users and administrators. All technical writers are invited and we’d love it if you can join us. You could even try pairing. It’s not too violent on a wiki. ;)

Where and when

Date: Thursday 4th November to Friday 5th November (two days).
Sydney, San Francisco or online: Join us at the Atlassian offices in Sydney or San Francisco, or work remotely and chat with us online via chat, Google Groups and the wiki.
The Doc Sprint wiki has the event details.  It’s also where we’ll be writing the quick start guides during the sprint.

Check out the Hall of Fame to see who was there last time. If you find some blank pages on the wiki, don’t worry. We’ll fill them as time goes by. Or you could sign up for a wiki username and update the pages yourself. Get an early start on the sprint. :)

If you’re interested in joining the doc sprint, just add your name to the list of attendees. Even if you’re not sure, you could add a comment on the wiki page to let us know you’re thinking about it.

Chocolate, T-shirt, fame and fun

This will be the bestest doc sprint ever!


Get every new post delivered to your Inbox.

Join 1,388 other followers

%d bloggers like this: