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.

Training workshop on using the iPad (and other tablets) as a documentation device

We’re considering running a training workshop on how to use the iPad and other tablets as a device for delivering documentation. The primary focus will be on the iPad, but we can also cover what’s possible on Android tablets.

If there is sufficient interest, then we’ll run a course.

We’ll cover items such as

  • How organisations are creating, in just 30 seconds, online magazines for “getting started” guides, tips and tricks, training guides and FAQs, using existing content from your Web site and blogs.
  • Apps for reading content
  • Tools for creating content
  • What works/ what doesn’t work
  • Implications for the future, how to use the iPad to gain and edge over your competition etc
  • IPad and PDFs – reading them on the device, copying them onto the iPad.

Let us know if you would be interested in attending such an event.

Location is likely to be in London or the South East of England.

Book review:”The Content Pool”

I was sent a review copy of Alan J. Porter’s latest book, The Content Pool: Leveraging your company’s largest hidden asset. It’s a well written book that’s ideal for anyone who is uncomfortable about the way their organisation creates and manages its written content, as well as anyone who simply wants to manage their content in better ways.

The book identifies and takes you through the key aspects of taking control of your content. I liked the book for what it left out, as much as what it covered. Content strategy and content management are huge topics, and it’s easy to feel overwhelmed by it all.

He could have covered topics such as the difference between short term and long term information, the provenance of information, and the attention economy (illustrated in the video below). However, he was right to leave those topics out and keep the focus on the main issues.

Alan raises key questions (such as why are you producing this content?), and helps steer you to the answers. The book also contains many anecdotes and case studies that keep you engaged throughout the book. He keeps reminding you to check any content system you implement meets your business goals.

He states:

However, being realistic, very few if any, companies are going to leap immediately from undervaluing their content assets to having them overseen and cared for by the highest levels of the organizations.

At the start of the book, he lists many examples of where poor content has had a major impact on an organization. Unfortunately, I don’t think these will persuade a CEO who thinks content is not that important to change their mind. I suspect they are more likely to change their mind if they felt their content was causing them to be left behind by their competitors.

The examples of Disney’s (which is mentioned in the book) and Coca Cola’s approaches to content strategy are likely to be a more convincing argument – big companies using content to gain a strategic advantage. We’ve also found other motivating factors to be directors who feel they don’t fully understand how the organisation is doing (numbers can only tell you so much, and meeting people is time-consuming) and CEOs who feel staff are not ‘getting’ the organisation’s goals and direction.

The final chapter provides great advice on how to sell yourself, and the idea of content strategy, to the organisation.

The worst aspect of the book is its cover drawing – it’s the wrong image for a professional book such as this. So, don’t judge this book by its cover – it’s worth adding to your bookshelf.

Designing documents for the iPad 3: the return of old design metaphors

After a few days of using the new iPad 3, it seems likely that, in the future, documents will be designed to take advantage of its retina display. Below are some thoughts on the new trends we’ll see in the way documents are designed for reading on tablet devices.

The paper metaphor

It has been good practice to present information published on paper and information published on screen differently. The limitations of computer screens, (for example, the screen resolution, screen flicker and eye strain issues) have meant long, linear documents don’t work on a screen. People like the resolution, portability and ability to make notes that paper provides. Paper simply is a great medium for deep learning and reading on the move.

It means organisations expect PDFs to be read on screen, when in reality they are printed out by users. Often the promised printing savings by distributing content online were never actually realised.

With the iPad 3′s screen, most of the limitations of reading on screen have been eliminated. Indeed, Apple is promoting it as a device for reading textbooks – which is can be an example of deep learning. It’s like paper in that it’s portable, you can make notes and you don’t get eye strain.

This means, we’re likely see documents on screen that look like documents printed on paper. It may be time for Technical Authors to dust off that copy of “Dynamics in Document Design”! For books that use Apple’s iBooks, we’ve found you tend to read page by page, instead of using the “peck and scan” approach common reading online content.

A new metaphor for online documents – Metro

The paper metaphor is not the only metaphor you can use. The new Metro UI, developed by Microsoft for Windows 8 and smartphones, is another design metaphor that is being adopted.

The Metro UI uses the following approaches:

  • Information is consolidated groups of common tasks to speed up use. This is done by relying on the actual content to function as the main UI.
  • The result is an interface that uses a “grid approach”, using large blocks (instead of small buttons, as well as laterally scrolling “canvases”.
  • Page titles are usually large and scroll off the page laterally.
  • The UI responds to users actions, by using animated transitions or other forms of motion.

An example of this is the Guardian iPad app:

According to The Guardian’s Andy Brockle:

We have created something that is a new proposition, different to other digital offerings. It works in either orientation and nothing is sacrificed. Instead of it being based on lists, breaking news, and the fastest updates it’s instead designed to be a more reflective, discoverable experience.

Displaying images

With the ability to pinch and zoom, readers have the ability to look at images in great detail. This may mean writers will need to present their documents in SVG format, but if we assume they stick to bitmap formats such as .jpg and .png, we’re still likely to see a change in the way documents that rely on images are designed. Instead of needing a series of separate images to display detail, the writer can provide a single image for the reader to explore. It also seems likely we’ll see images that contain “layers” that can be peeled off to reveal the underlying details.

Unresolved aspects

We’re at the beginning of the process of making the most of portable devices with “real-life” displays, so document design is likely to evolve further. It’s still unclear what is the best navigation UI for iPad3 readers.

The bear trap

There is a huge bear trap waiting to catch out organisations – that they assume what works on iPad 3′s retina display will work on screens with lower resolutions.


The more you use the iPad’s new screen, the more you realise it will change the way documents are designed in the future – the biggest possibly being a move from on screen content being structured laterally instead of vertically. With predictions of there being more iPads than citizens of the United States of America by the end of next year, there’ll be more and more reasons for optimising content for the iPad 3.

Cherryleaf’s online induction technical author course gains ISTC accreditation

This Institute of Scientific and Technical Communicators (ISTC) has today accredited our £175 Technical author basic/induction training course. As this is an independent assessment of its quality, we’re delighted to have this course accreditation.

The ISTC’s reviewers provided us with a lot of feedback. This was more than a paper exercise and Technical Authors are never shy in making suggestions and comments to their peers. In light of some of the comments, we’ve tweaked some of the copy on the Web page . We’ve explained this is a course for people working in IT, rather than those working on planes, trains and automobiles type projects. They also picked up that we’d mentioned “Agile” and “User Assistance” in a module without explaining them – a fair point. There were other discussions, such as, should we have mentioned any documentation standards? If so, which one?

The course modules remain unaltered, although we have useful suggestions to implement whenever the course is revised.

What does the iPad 3 mean for Technical Authors? Part 4: Its application in a documentation setting

In this post, we’ll look at potential applications for the iPad in a documentation setting.

Portable documentation

The iPad is a portable device, so where people and documentation need to be portable, it’s likely there’ll be an interest in using the iPad.

For example, we’re currently looking at the iPad’s application within a hospital setting, where staff may need to refer to clinical and non-clinical procedures. Also, the Federal Aviation Authority has approved use of the iPad as a pilot’s Electronic Flight Bag.

So why not use a laptop to do this? The iPad’s advantage is its battery life, weight, ease of use and price. These factors, however are also true for ebook readers. Where graphical content is less of an issue, then an ebook reader, such as the Kindle, may offer a cheaper solution.

So Why not use a paper manual to do this? It’s harder to update the content and the pictures don’t move.

Visually rich content

Apple is promoting heavily the iPad’s ability to present textbooks that are visually rich, containing interactive graphics, 3D images and the ability to zoom and pan. Although a Technical Author can deliver most of these today, using a number of Adobe’s software applications for example, Apple has the knack of making the most of these capabilities.

Chargeable content

Organisations have the opportunity to deliver content in new formats, such as iBooks and as apps. Although these can be supplied free of charge, users will be used to paying for these media formats. By creating a more richer experience for users, there maybe scope to make money from documentation.

Ease of use

Apple has created a device that is easy and intuitive to use. In short, the iPad offers the promise to Technical Authors that more people may read the content, particularly the technophobic.


There will almost certainly more applications, and it’s possible that “first mover advantage” may come into play. The first entrants might gain market share that followers may not be able to regain.