Category Archives: book

Post navigation

The Language of Technical Communication book is a collaborative effort with fifty-two contributors defining the terms that form the core of technical communication as it is practiced today. Cherryleaf’s Ellis Pratt was one of the contributors.

Each contributed term has a concise definition, an importance statement, and an essay that describes why technical communicators need to know that term.

There’s a joke in education along the lines that students are taught the notes their teachers wrote down at university 20 years earlier…without going through the heads of either.

I mention this because there have been a number of technical communicators who have started to question the technical writing best practices that have been taught to student Technical Authors for the past 30+ years. At Cherryleaf, we show on our advanced technical writing techniques course how some of the largest websites have been breaking the generally accepted rules for writing User Assistance – companies that test and test again to see what works best for their users. Ray Gallon of CultureCom has been developing his cognitive approach to User Assistance, and Mark Baker has been developing and promoting the idea of “Every Page is Page One” (EPPO) Help topics.

Mark has published his ideas in a new book called “Every Page is Page One“. I was asked to review an early draft of the book, and, over Christmas, I was sent a copy of the published version.

In a nutshell, Mark’s argument is that, with Web-based content, you don’t know the context in which people are reading a Help page. You cannot assume that they have read any other pages prior to reading this topic. Therefore, you need to treat every page as Page One, the starting point, and include more introductory, contextual information in your topics. He argues that most Technical Authors have misunderstood minimalism, and the EPPO approach is actually more consistent with how John Carroll (the creator of minimalism) recommended User Assistance should be written.

The book provides recommendations on the level of detail you should include on a page before you need to create a new topic, and when and where to create links to other pages. He also compares EPPO to Information Mapping and DITA, and outlines how EPPO can complement these standards.

Reading the early PDF draft with a reviewer’s eye was struggle at times, but reading the final version in printed book format was an easy and enjoyable exercise. Perhaps reading some sections for a second time helped, as well.

We agree with a great deal of Mark’s ideas. We agree with the general idea of self-contained topics that provide the context for a task. We agree with the need for mini-Tables of Contents and a bottom-up approach to writing. We agree that tasks should include some contextual information. We agree online content can be atomised too much. We also liked his analysis of why screencasts are so popular, and the secrets to their success.

We have a few minor issues. Mark cautions against duplicating content on more than one Web page, because it’s bad for Search Engine Optimisation. We believe you should write efficiently in a way that’s best for the user, and that it’s up to the Search Engines to improve their algorithms so they can differentiate between “good” duplication and “bad” duplication. Google should be adapting and learning from the way good content is written, not us having to create sub-optimal content in order to satisfy Google.

It’s a book for people involved today in writing online User Assistance. Although the book is very clear and well structured, you probably need to have some experience of creating User Assistance to fully understand everything that’s covered in the book. It’s an important contribution to the discussion over whether technical communicators have focused too much on production efficiencies to the detriment of creating content that’s actually of value to their users. It’s worth getting a copy of this book.

The bookshelves here at Cherryleaf are double stacked, and we’ve received another book this week to read and then store.

So it seemed like a good time to mention which books we’d advise Technical Authors to read.

This most recent book was published by XML Press, and their publications are well worth looking at. We have quite a few books from them. Some were review copies (i.e. free), and others were ones we bought.

Most Technical Authors use style guides, and both Microsoft and IBM publish style guides you should consider buying. Style guides help you make sure you’re using the right terminology. They can also help your manuals complement the big vendors’ documentation.

The best book I’ve read in 2012 wasn’t written for Technical Authors. It wasn’t even published in 2011. It was written by one my fellow speakers at the STC Conference in Chicago, and it was one that was the most thought provoking books I’ve read this year.

Matthew Syed is a British sports journalist and former three times Commonwealth Games gold medallist, who has been investigating what is needed to make people excellent at doing any task involving complexity.

He argues that natural talent, your genes, are far less important than many people think. What’s important is practising what you can’t quite do. He argues we grow if we test our limitations, because our body adapts.

So what on earth does that have to do with developing software and Technical Authors? Syed argues there are two opposing views regarding success:

One “school” believes talent is what makes success. This means that if you fail, you believe it’s because you don’t have enough talent. Therefore, you’re likely to give up.

The other “school” believes success is all about practice – the quantity of practice, the quality of teaching and the willingness to test our limitations. This means that if you fail, you believe you can succeed with more perseverance and effort. It’s an opportunity to adapt and grow.

I would argue the whole philosophy of User Assistance is based around the belief that talent is all about practice. It’s easy to forget that others may think it’s all about talent – your developers may believe some users fail because they are stupid, and some of your users may believe they’re just not good enough to succeed. It’s worth checking what they believe.

Another implication is that we should provide assistance and guidance to users as they are doing the task. We should try to avoid interrupting their flow. This suggests providing Help and advice within the application screens themselves.

Thirdly, we should praise people for their effort rather than for their talent.

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

Someone who has used Confluence or another similar application, but sees themselves as a beginner

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.

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.