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.
Thank you for such a considered and lovely review. I’m so glad that the best practice guidelines and tips ring true for you too. That’s praise indeed. It will be interesting to see what your team members think about the book.
On another note: What an absolutely gorgeous blog site! The first time I read this post, I was on my mobile and so didn’t get the graphics. Now I’ve popped in to add a comment. It’s a pleasure to visit such a unique site.
Thanks, Sarah! Somehow I missed your comment until now, sorry for the slow reply.
Any idea if Confluence will allow you to import from an RSS feed? We’ve got some rogue WordPress boglgers that we would like to migrate to Confluence, but the fear of a manual import is holding us back at the moment.
I don’t know, but I’ll ask around and see if I can get someone to comment here with an answer for you.
Hallo Yurina and matthew
That’s an interesting question. I have not seen anyone ask or answer it, and I don’t know the answer myself.
There isn’t a good solution for importing from HTML to Confluence. The Universal Wiki Converter offers a partial solution:
Alternatively, you may be able script a solution using Bob Swift’s CLI tool:
The forum called “Atlassian Answers” is a great place to ask a question like yours. There are a number of skilled people on the forum, Atlassians and others, and I hope someone comes up with an interesting response for you:
Comments are closed.