Confluence, Tech Comm, Chocolate

As I mentioned in an earlier review of writing-related books, I am a writer. I write for a living. I write technical documentation, books, occasional articles for magazines and websites, and more. This review covers a book that has been helpful to me primarily in technical writing.

Wikis are wonderful. There, I said it right at the beginning. I’m biased. I’ve written documentation using everything from word processors like Microsoft Word and LibreOffice to XML variants like DocBook. I’ve hand-written entire suites of documentation using HTML and XHTML. I’ve also used various wikis, such as MediaWiki, MoinMoin, and the topic of the book in this review, Confluence.

Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication came out earlier in 2012. It was published by XML Press, which specializes on content for technical communicators (also known as technical writers, technical documentation specialists, and so on). The author, Sarah Maddox, works as a technical writer for Atlassian, the creator of Confluence and other software tools.

This book fits a useful niche between marketing materials that are more useful in an early product evaluation stage and technical documentation that is most useful during the implementation stage. Planning your documentation comes in between these two stages and is a vital step that is often poorly documented, especially in terms of planning and creating technical documentation on a wiki. This book gives a wealth of practical advice for this stage.

In addition, Sarah Maddox includes in the book all the information that a complete novice requires. Topics like what is a wiki or how is a wiki used on a day to day basis for technical communication are covered and covered well. The reader receives specific instruction on useful topics like creating content for reuse, using Confluence as your single source for output to other formats, creating templates and styling, importing content from other formats, creating documentation as a team, using a wiki within an Agile context, and performing content reviews on the wiki itself.

I’ve used Confluence to create technical documentation from scratch in previous projects. The best practice guidelines and tips in this book ring true to me from my experiences. My current project uses Confluence as one tool among many. I will be sharing the book with my colleagues to see how we can use it even more effectively.

If you are a technical communicator and are considering Confluence as a medium for documentation, take a look at this book before you do anything. In addition, I believe the book would be useful to share with both technical collaborators like software engineers as well as less technical collaborators like program managers or sales staff. The latter generally have more direct communication with customers, either through software requirements or personal interaction, and the book will help each understand and determine whether Confluence is a good fit for your technical communication, for your company workflow, and also for your sales and bottom line.

Disclosure: I was given my copy of this book by the publisher as a review copy.