Book review: Confluence, Tech Comm, Chocolate

I was sent a review copy of Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication, by  Sarah Maddox. It’s about using wiki technology for developing and publishing technical documentation, using the Confluence platform, the emerging trends in the creation of User Assistance and, in places, chocolate.

Confluence, Tech Comm, Chocolate

The book is aimed at three audiences:

  1. The person who isn’t sure what collaboration tools and wikis are, and is not yet fully convinced these are platforms they should use for producing and publishing technical documentation
  2. Someone who has used Confluence or another similar application, but sees themselves as a beginner
  3. Advanced users of Confluence.

The author manages to pull it off  – all three groups will find the book interesting and useful.

For the skeptics, Sarah raises and answers a great question:

Isn’t a wiki just a puddle of chaos?

The problem with the word “wiki” is everyone thinks of Wikipedia, with its complicated authoring environment and occasional errors. Sarah explains not all wikis are like Wikipedia, and how Atlassian, the makers of Confluence, struggles to describe the software (it currently says it “provides collaboration and wiki tools”). In fact, Confluence is a tool that can publish EPUB ebooks, PDFs, Word documents, HTML, DocBook files and, probably quite soon, DITA files. It has a rich text editor that looks like Word. It’s a wiki that doesn’t look like a wiki.

The book itself was written in Confluence. Comprising 477 pages, there’s a lot of “meat” in this book. We’d consider ourselves as knowing a lot about Confluence, having used it to build solutions for a number of clients, but there were many useful nuggets of new information.

Enthusiasm oozes through almost every page. That’s partly because Confluence is one of those tools that causes clients to get excited. They very quickly realise the potential outside of the original project. It’s also partly because the author is passionate about the subject.

Examples are built around a hero (heroine, actually) called Ganache, and this approach works well.

The book also looks at new trends in User Assistance – where technical documentation is going and how it will be created. A Cherryleaf article is mentioned in passing. It looks at working in an Agile software development environment, and how a collaborative authoring environment can help reduce the authoring bottleneck Agile can produce.

Sarah also highlights the weaknesses of authoring in this environment. There are issues around round tripping (and whether it’s needed or not), in particular.

Technical Writers will also have questions about translation and localisation of content, which is touched on only briefly. Publishing to .CHM files isn’t covered. However, there is a wiki that complements the book, so readers have the opportunity to raise these questions with the author (and discuss them with other readers) there.

If you’re interested in collaborative authoring, wikis, Confluence, chocolate, working in an Agile environment or where technical documentation is going, then it’s worth getting this book.

The User Manual 2.$

Here is an interesting interview between Robert Scoble and Aaron Fulkerson of Midtouch on how MindTouch’s technical communication software is changing how people work together at big companies.

“We started seeing more and more of our customers—Intuit and Microsoft, Intel and Autodesk and Mozilla – launching these documentation communities where they have a body of content for user manuals,” explains Fulkerson. “Just imagine taking ten DVDs of video and text and putting it on the internet for the first time. What does that do for your search engine optimization? And then building a community around that where [customers] can contribute to it. They’re registering with the site, they’re sharing information with you about how you can improve this or that—of course it’s helping lead generation.”

“Enterprise wikis and documentation communities may sound like rather different applications, but Fulkerson asserts that they’re actually the same use case—they’re just applied to two different things. “One is internal around enterprise systems, the other one is external more around social media sites. But they’re both delivering collaboration and social capabilities in a web-based environment that’s connecting systems together.”

Contact us if you’re interested in looking into Mindtouch’s software.

Review of “WIKI: Grow your own for fun and profit”

XML Press kindly sent me a reviewer’s copy of Alan J. Porter’s book “WIKI: Grow your own for fun and profit”. I interviewed Alan earlier in the year (which you can see on the Cherryleaf YouTube Channel), so it was good to see the book that he was mentioning in the interview.

It’s important not to think that wikis only = Wikipedia. You could argue that applications such as Confluence and Mindtouch 2010 are wikis as well – wikis enhanced with powerful tools for software user documentation, but wikis, nonetheless.

As Scott Abel says in the introduction, most organisations have yet to manage the art of managing content. They make two common mistakes: (1) they see content as either documents or structured data, and (2) they see it as purely a software problem.

Wikis offer technical communicators a handy route into an organisations for them to tackle poor content. That’s because wiki software is generally very cheap and the techies like them. There are still issues around “round tripping” (getting content in and out, and back in again) and link management, but these are not insurmountable.

Alan, I’m pleased to say, has not been seduced by the software, but has set the use of a wiki within a very usable framework. He’s spot on when it comes to the benefits a wiki can offer and the implementation approach to take.