Book review: Every Page is Page One

Every Page is Page One book coverThere’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.

Which books should Technical Authors read?

Woman reading bookThe 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.

Cherryleaf offers a couple of Kindle books for a just a few pounds.

Then there are the technical writing “classics”. In this group, we’d recommend you look at books by Ron BlicqJohn Carroll, JoAnn HackosKaren Schriver and Joe Welinske.

Specialist books like these are not cheap, unfortunately; a decent collection of technical writing books will set you back at least £100.

Which other books and authors would you recommend to Technical Authors? You can use the comments box below to share your opinion with others.

(Flickr image: Will Ockenden)

The best book for Technical Communicators in 2012

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.

One of the subjects it explores is curiosity:

Continue reading

How software users become champions

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:

  1. 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.
  2. 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.

Bounce

BBC Radio 4 Four Thought

What do you think?

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.

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.

New review of “Trends in Technical Communication”

Phil Stokes has written a review of our Trends in Technical Communication ebook in the Autumn 2011 edition of the ISTC’s Communicator magazine:

Overall, though, this book does what it promises to do. It provides an overview of trends in technical communication and sets out a vision for the future. If you are wondering what skills you are going to need tomorrow and where the future lies for our profession , this book is a good place to start.

Phil gave it 4 stars out of 5.

Voltaire, typos, and the jitters – writing the IBM Style Guide

This guest post is from Peter Hayward of IBM (UK):

Voltaire said that “the art of medicine consists in amusing the patient while nature cures the disease.” Technical editing is a bit like practising medicine. It has a focus on both prevention and cure, except we don’t have nature on our side. With editing, nature tends to maintain the status quo; if the doctor doesn’t attempt the prevention and provide the cure, the disease persists. Writers need some sort of guidance to help them through the minefield of trying to write consistently, clearly, and concisely, while still following all the rules that editors seem to enjoy imposing.

Like many organisations, IBM has made up its fair share of rules and guidelines. A council of about 15, drawn from across the company’s writing community, is charged with looking after them, making sure they stay consistent and up to date. These guidelines have been available internally for many years, but we recently recognised that this accumulated wisdom might have a use in the wider world of technical writing.

So a sub-group of editors from that Style and Word Usage Council set about turning the guidelines into something fit for publication, removing all the boring internal bits, making sure we didn’t upset any sensibilities, or run foul of our legal overseers.

IBM uses DITA markup these days for most technical documentation, so we decided to follow suit with our scribblings. As well as providing our text to the publishers in that format, we were able to transform it daily into HTML and put it in a structured help system (“information centre”) based on Eclipse so that we could keep track of what we were doing.

I guess that to a big publisher, our little book was just one more title on their list. We naturally saw it as much more. Although, thinking about it, such a book actually is different from other titles, which is making me just a little apprehensive. If you want to use trendy jargon, you could say it’s a “metabook”, writing about writing, which means that you’re inevitably setting yourself up for a fall. If you spot a typo in most books, it’s usually little more than an annoyance. Typos and mistakes in books that purport to tell the reader how to write properly, invite a rather different response.

So if you do get your hands on a copy of the IBM Style Guide (“available from all good bookshops”), please be gentle. We tried to persuade the publishers that it was you, discerning author, who we were writing for, and not your average “punter”. OK, so it’s not fair to pass all the blame for errors to these editors’ editors. But I’m a little nervous. Of course it’s full of good stuff, well written and without blemish. Really it is. But I just have this feeling, that as the very first copy I handle falls open at random…