Wikis have been part of my professional freelance writing and technical communication lives for a number of years now. I’ve used them extensively and even maintain my own wiki; I’ve written with and about them; and I’ve even set up a few documentation wikis. While a couple or three people have generously suggested that I’m an expert in this area, I’m not. Far from it, in fact. I still have a lot to learn.
To do that, I turn to others who know a lot more about wikis than I do. Folks like Stewart Mader, Alan J. Porter, and Sarah Maddox. And it’s Sarah Maddox, or at least her new book, that sparked this blog post.
Being the aging, jaded person I am I don’t get excited about much. When I learned that Sarah was working on a book on using wikis specifically for writing documentation I got excited. As a technical writer for Atlassian (the folks behind the Confluence wiki), Sarah lives documentation and wikis — all of Atlassian’s documentation is delivered with a wiki. I was expecting a comprehensive look at using a wiki for documentation. And I wasn’t disappointed.
Let’s take a closer look at Confluence, Tech Comm, Chocolate.
Jumping in
Confluence, Tech Comm, Chocolate is an end-to-end tutorial on using a wiki for documentation, written in a lively style. It starts off with an introduction to wikis and takes you on a quick tour of Confluence. From there, your learning begins. Each chapter is a lesson, walking you through what you’ll need to know to successfully use a wiki to write, edit, review, and deliver documentation. At end of each chapter is a recap of important points that were covered, along with more than a few references.
As I said a moment ago, the book is written in a style that’s easy to read and never boring. Walking you through the book is a character that Sarah created named Ganache. She’s a technical writer (surprise, surprise!) and it’s through the filter of Ganache’s experience that you see how to effectively set up a wiki for documentation.
Be warned that this isn’t a short book. Confluence, Tech Comm, Chocolate weighs in at 477 pages. But unless you’re an expert wiki user, you’ll learn something from many of those pages. It’s also heavily slanted towards users of Confluence. But you can apply the information in the book to other wikis. More on this in a bit.
Now that the preliminaries are out of the way, let’s jump into some of the section of Confluence, Tech Comm, Chocolate that I found interesting and useful.
Writing and structuring information
Well written and well structured documentation is far more useful to readers than unrelated bits of content. As Sarah writes:
Isn’t a wiki just a puddle of chaos? Doesn’t it always look like an unimaginative scrabble of words, with no form to enhance the meaning? Not necessarily!
To help you avoid creating that puddle of chaos, Sarah spends several chapters looking at how to plan, structure, and create content on a wiki. That involves planning your wiki, changing its appearance because looks can matter, and to reuse content whenever possible.
Also, wikis are prime candidates for creating documentation via topic-based writing. Each page can be a discrete piece of content, connected with other content via links and cross references. Just about anything you can do in tools like FrameMaker or Flare, you can do on a wiki. Including delivering online help, a subject to which Sarah devotes an entire chapter.
Engaging your audience
As I keep pointing out to people (some of whom should know better), technical communicators aren’t creating documentation for themselves. We have an audience that we need to engage and capture. That’s not easy. But luckily there are tools out there to help us.
Like what? Like social media, for example. As Sarah points out:
Social media offers new ways for getting readers involved in the documentation and for getting technical communicators involved with their readers. Never before has it been so easy to engage with so many people at once.
How? By:
- Making readers aware that the documentation exists.
- Getting feedback from readers.
- Influencing what people say and think about documentation.
- Making documentation one of the first, if not the first, point of contact
You can do that, as Sarah points out, by not only getting the attention of internal teams and bloggers on the wider web, but also by using tools like Twitter to publish tips and point to information that readers can use.
But engaging your audience doesn’t stop with pulling them into your documentation. If you can, get them involved in leaving comment or, even better, adding to the documentation. Even nowadays, I know more than a few technical communicators who are loathe to allow reader to touch their documentation. But as I pointed out earlier and elsewhere, it’s not our documentation. We’re writing it for our readers, and many of them have insights that we can use to improve those docs.
Sarah devotes a whole chapter to this, called “Updates by everyman,” and offers some solid advice on why you’d want to involve your readers in updates, as well as information on copyrights and intellectual property. That chapter cleared up some of the questions on this subject that have been nagging me for a while.
But I don’t use Confluence …
So what?
I read a short review of Confluence, Tech Comm, Chocolate at an online bookseller. The person who wrote that review claimed that he couldn’t figure out how to apply the lessons of this book to other wikis. That left me scratching my head. Sure, this book is filled with examples of the features and functions related to Confluence but if you know your wiki (or are willing to learn about it) then you can adapt a lot of the information in this book to your tool of choice. Like what? How about, for example:
- Plugins — Most wikis support them. And while they might not be as powerful or as flexible or even as numerous as the ones available for Confluence, chances are you can find plugins that suit your needs. DokuWiki, for example has plugins that enable you to create a book by selecting various pages or to create and edit SVG images.
- Namespaces — All wikis support namespaces. Namespaces enable you put compartmentalize your documentation. You can have namespaces for user guides, administrator guides, and online help. Never the twain shall meet, unless you explicitly link between them.
- Importing content — Not all wikis support this, but the ones that do often do it well. MindTouch, for example, has a feature that lets you import a CHM file.
- Content reuse — A lot like snippets in Madcap Flare or insets in FrameMaker, most wikis allow you to reuse content. You can read about how I did that with Twiki here.
And those are just the examples that popped into my head as I was writing this post.
The lessons of this book aren’t restricted to the tool. Earlier, I mentioned the chapters which discuss how to engage readers. And if you can’t find a way to take the information in chapters 6 and 7 (on developing content and structure & style, respectively) then I suggest you find someone who can.
Adapting the information in Confluence, Tech Comm, Chocolate to your wiki might take a bit of time and thought, but it’s worth taking that time and doing that thinking.
OK, where does chocolate come in?
If you’ve ever read any of Sarah’s blog posts or tweets, you know that chocolate plays a role in her personal and professional lives. It’s a treat. It’s a good energy boost. And it’s a good way to engage (I hate to use the word bribe) developers and subject matter experts.
Throughout the book, you’ll find little sidebars containing quotes from various technical communicators on what role chocolate plays in their professional lives. If nothing else, those sidebars offer a nice break. And some good ideas for snacks!
Summing up
While I read the book from cover to cover (except for the index), I didn’t look at everything in the Confluence, Tech Comm, Chocolate in this review. There’s a lot more between the covers than what I’ve outlined above. And it’s useful whether you’re new to using wikis for documentation or if you’re an experienced hand.
Confluence, Tech Comm, Chocolate bridges the gap between the theoretical and practical sides of implementing a wiki for documentation. And its tech comm focus is something that makes it an excellent companion to books like WikiPatterns, Writing in the Open, and WIKI: Grow Your Own for Fun and Profit. If you’re a technical communicator looking for solid, practical advice on implementing a wiki for documentation then grab a copy of this book. You won’t regret it.