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.

Technical writing in the Cloud

One of the most popular developments in computing in recent years has been the emergence of cloud-based computing and Software as a Service (SaaS). Examples of cloud-based computing include Google’s GMail: Instead of an application being installed locally on a user’s computer, it runs on a remote server, accessed via the user’s Web browser.

So is technical writing likely to move to the Cloud? Let’s look at the different approaches.

Why would you want to write using a cloud-based application?

There are a number of reasons why a Technical Author might want to use a cloud-based application. The first reason is cost. Instead of purchasing an application, cloud-based applications are typically offered on a monthly fee basis. If you’re looking to move to a DITA authoring environment, this spreading of costs could prove an attractive alternative to the upfront costs associated with buying a DITA solution.

There are other reasons, why you might also consider moving to a cloud-based solution:

  • If you have staff, a technical writing partner (such as Cherryleaf) or contractors working remotely, cloud computing means you can quickly and easily add them into your authoring environment.
  • If you want to work in a collaborative authoring environment, cloud-based applications typically enable you to do that.
  • If you use a third party company (such as Cherryleaf), you have the opportunity, at a later date, to log into the system and make any minor updates (following updated releases of your product) yourself.

Check in/out

You don’t necessarily need to move to a cloud-based environment, if you want to have remote workers and/or collaborative authoring. The most popular authoring tools, such as RoboHelp, FrameMaker and Flare, use a check in/out model instead of a cloud-based approach. Writers can “check out” a topic from a project and work on it remotely. They can then “check in” the completed topic back into the project, via email or SharePoint.

Your authors will all need to have the Help Authoring Tool on their computers, and you cannot watch them as they write, but it’s worth considering.


If you’re looking for a SaaS authoring tool, then there are a number to consider:

  • DITA-based authoring applications and services, such as Doczone, DITAweb and Stilo Migrate
  • Help Authoring Tools, such as HelpConsole and Author-it Live
  • Wiki-based technical authoring applications, such as Mindtouch Cloud and Atlassian OnDemand
  • Word processors, such as Google Docs

You’re usually unable to add any additional plugins, which you’d be able to do if the software was installed on your computers or servers.

You may also need to consider where your data is actually being stored. Data privacy rules differ in the USA and the European Union –  the USA’s Patriot Act, for example.

Your own private cloud (VPN)

Some organisations simply add remote workers to their existing network. The organisation has its own private cloud, a Virtual Private Network (VPN). Typically, it’s up to the IT department as to whether a remote user will be given access to a system. You may need to acquire licences, and you may need to wait for IT to set this all up for you.

An alternative approach is to create a private cloud for your own department. You can create a server in the Cloud, using Amazon’s EC2 service, or using alternatives from companies such as RackSpace or Microsoft (Azure). On this server, you could install for example, a customised version of the Authoring application (containing all the plugins and macros you require), and provide remote workers with a web address, user name and password for them to log in. With VPN server prices starting at $20/month, it’s an affordable option.

If you decide to do this “under the radar” (i.e. don’t tell the IT department you’re setting up your own VPN), you need to make sure you’re conforming to your organisation’s IT security policy. Otherwise, you could be in trouble.

Are you writing in the Cloud?

The reasons for using cloud-based applications seem to be as valid in the Technical Publications department as in other departments. So it’s likely we’ll see a growth in the uptake of this type of service.

  • Are you writing in the Cloud? How have you tackled this problem?
  • Is writing in the Cloud a good idea?

We welcome your comments.

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.

Whither wikis?

The BBC’s Rory Cellan-Jones reports on Wikipedia’s challenges:

Will the online encyclopaedia that has become the first destination for millions of web users searching information end up withering away, as its worker bees lose interest in keeping it nourished? That’s the question raised by a study of Wikipedia editors carried out by a Spanish academic for the Wall Street Journal.

It shows that editors are giving up on Wikipedia far faster than new ones are joining, with a net loss of 49,000 editors in the first three months of 2009. 

At the same time, Wikipedia’s popularity continues to grow:

Even if it does become more difficult to get people interested in contributing to Wikipedia, there’s no doubt that user numbers just keep on growing. Wikipedia itself reckons between 28% and 37% of the UK internet population are regular users. 

In other words, users love it, but for writers and editors, it might be losing its lustre. As one of the commentators on the BBC Web site has posted:

MediaWiki is a very clever bit of software, but from the users point of view it is a minefield. If you are a writer, then you want the medium you use to be familiar to you – you certainly do NOT want to have to learn an entire new syntax.

Those companies hoping for a worldwide community of unpaid enthusiasts may need to confront a nasty reality:

  1. They might need to reward contributors and editors
  2. They might need to look further afield than the MediaWiki platform.

Six reasons why your wiki isn’t working

Wikis are a great way to create and publish documentation online, but there are many wikis that haven’t worked. They comprise just a few pages of incomplete, out of date information.

Why is that? Why do some wikis work and others just fail?

Here are six key reasons why:

1. The wiki isn’t managed

A wiki should be treated in many ways like a teenage party. If all you do is provide a space for people to entertain themselves and you then leave them to it, you shouldn’t be surprised to find that, when you come back, the place is in a terrible mess or everyone’s left.

Someone needs to edit, moderate and even lead. In other words, the content needs to be managed.

2. Readers struggle to find the information they need

Wikis are designed to have a flat information structure. The intention is you’ll find the information you need in just a few clicks. Wikis rely mostly on people finding information by using the Search function.

Unfortunately, it just isn’t always possible to do this successfully, particularly if you’ve got lots of information. Complex information does need, sometimes, a long navigation trail down a path. What’s more, the Search Engines supplied with many wikis just aren’t up to the job.

So you may need to use an alternative Search Engine, and one option is to use Google’s chargeable service, where you use their software to provide the search results. You may also need to create a series of pages that act as “menu” or “landing” pages – collections of links to relevant pages.

3. You’ve picked the wrong software

Just because Wikipedia chose the MediaWiki software platform doesn’t mean it’s the right software for you. There are other free wiki platforms, such as TWiki, which have better capabilities (such as marking “official” content from other forms of information and printing content to paper).

4. You don’t have enough people actively participating

Many people start a wiki with the belief, “build it and they will come”. Unfortunately, that’s unlikely to happen. Studies of wikis have indicated a 90:9:1 rule: 90% of people will be readers, 9% will be editors and 1% will be writers. Unless you have a huge audience, you’ll need to ensure someone is responsible for writing content.

5. You actually wanted people to discuss and converse

Although wikis do include a discussion tab, it’s often buried away and seldom used. It might be that a wiki isn’t actually what you need. You might be better off with a Blog, Google Wave or even a Web authoring tool that has the capability for users to append comments to the bottom of a page.

6. You’ve created an island of information, and it’s hard to re-use the wiki content anywhere else

Wikis can end up containing some great content, but it can be really hard to re-use that content elsewhere – for example, moving content from an internal wiki to a paper user guide, your Web site or a Help file.

The result is having to maintain two versions of the same content, which can lead to inconsistencies, errors and extra time and cost. Organisations are developing tools to manage wiki content, (looking at issues such as how do you exchange content stored in structured XML formats and wiki syntax), which are well worth investigating.

Choose your solution wisely, if you want to export your wiki content to somewhere else.


Wikis are great when you want people to see a work-in-progress or if you want people to collaborate and contribute to a document. However, it’s easy to get things wrong or expect too much from a wiki.

Make sure you know what problem you want to solve, which capabilities you want your solution to have and then you should choose your platform on that basis.

Finally, you may find you need someone to oversee the information – a professional technical author, copywriter or an editor might be a useful resource in this situation.

Google Wave – A case study in 21st Century User Assistance

Google’s latest product, Google Wave, provides a case study in how User Assistance is sometimes provided to users for popular Web-based applications. It is a useful case study, because:

  1. The application contains unfamiliar concepts and tasks;
  2. Google hopes it will be used by many people; and
  3. It’s from a major provider of software.

While the application clearly works (although there is some uncertainty as to whether some behaviours are “features” or bugs), this unfamiliarity means that users could give up and reject the application.

We need to bear in mind the application is currently available in “limited preview”, to an initial tranche of people. So what can we discover?

1. A lot of user assistance provided so far seems to be promoted towards “innovators”. The information is aimed at providing an overview of the application and outlining the key concepts. So are users are left to work out how to do carry out tasks for themselves? Is it assumed they are technically clever, motivated and interested enough to work a lot out for themselves?

This may not be a bad thing. Indeed, a phased documentation approach was recommended by IBM’s Mike Hughes PhD. at the UA Conference Europe 09.

The most frequently found User Assistance services that have been provided by Google are:

There is currently no comic-style guide, such as that provided by Google for Google Chrome.

2. There is User Assistance for end users. Surprisingly, judging by the articles written by users, very few people are referring to Google’s “Google Wave Help“. Is this because:

  1. Few people know about this?
  2. It’s not very good?
  3. People don’t/won’t use Help?

We don’t have one of those early invitations to use Google Wave, so it’s unclear to us whether the application steers users to the Help.  (see Update below) The Help itself provides short, clear instructions on how to carry out the main tasks. However, it’s almost exclusively text based, with no means to comment on the information. What’s more, it doesn’t really interlink with the other information sources that Google has developed.

3. Additional User Assistance has been created by users, journalists and third party providers. Searching Google for “Google Wave” provides links to 12,500,000 articles and ‘”Google Wave Help” 26,200 articles. The third party information appears to be aimed more at end users and comprises mostly:

Many are in the form of Blog articles containing hundreds of comments.

There also currently 499 Google Wave videos on YouTube – these are mostly user overviews.

4. Using Google to ask questions such as “how do I manage a Google wave” provides you with links to Google Wave Help (which answers the questions) and some third party articles (which don’t). However, asking “How do I create a Google wave” does not provide a link to a useful answer on the first page of the search results.

5. All the User Assistance provided by Google appears to be in English only. Searching for “Google Wave Hilfe” (“Google Wave Help” in German) provides no meaningful links.

6. UPDATE. We now have access to the application itself. Within the application, users are provided with a form of embedded Help – an intial Wave that includes a 2 minute “getting started” video (by “Doctor Wave”) and links to waves with more information:

  • Getting started with Google Wave
    “This is a wave with quick tips on the basics of using Google Wave, including some how-to videos.” The document is a read-only wave, so it behave just like classic online Help, albeit containing a lot of animated tutorials. What’s strange is that it seems to contain different information to the Web-based Google Wave Help pages.
  • When to use Google Wave
    “Explore example waves and watch a video (8 min) to see how you can use Google Wave with friends and colleagues.” Again,  this is very Help like, it contains a talking heads video and it seems to contain different information to the Web-based Google Wave Help pages. 
  • Google Wave extensions
    “Install extensions to Google Wave to bring rich content into your waves and integrate with other systems.”

There is also a “Help” link button at the top of the screen. This links users to the Google Wave Help pages.


It’s too early to form any firm conclusions, and we need to keep asking questions and observe:

  • Will Google provide additional User Assistance over time?
  • What other user assistance will emerge, and from where?
  • Will Google Wave be a success or not?

However, one thing seems to be clear: Today, users will need to devote considerable time to finding and reading the lengthy videos, articles and conversations that exist around using Google Wave.