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.

What would a Technical Author ask from Santa?

Santa Claus - WikipediaSaint Nicholas’s day has passed, which means Christmas is getting close. So what would a Technical Author ask from Santa Claus?

One thing we could request is the ability to embed one Google document inside another. That would mean that Google Docs could support some basic content reuse.

Another would be to request Madcap Flare’s DITA support to be extended, so that you could create edit native DITA files.

We could ask him to provide a standard technology format for providing Help for mobile applications.

We could also ask him for a way to use Siri and Google Voice Search to interact with our user guides.

So what would you ask Santa to bring? Please share your thoughts and ideas below.

Changing times in technical communication 2 – Workflow

Science Museum/Science & Society Picture LibraryWe’ve been on the road in recent days and weeks, visiting different documentation teams, and we’ve found there are distinct signs of change. In this post, I’ll look at how we’re starting to see the workflow for creating User Assistance beginning to change.

We found many documentation teams overstretched and starting to be asked how they could create content for new products that were coming along. Some organisations have decided they can only deal with this extra workload if they rethink the workflow for how content is created.

Continue reading

Deciding between a contract and a permanent Technical Author

Flickr vacancy image CC by LOLen One question that seems to being asked a lot by our clients at the moment, is whether they should hire a permanent or a contract Technical Author.

At first sight, it may appear that a contractor will cost more than taking someone on as an employee, but that’s not always the case. With a contractor, you’re only paying for the days that person works. You’re not paying for public holidays (8 days), sick pay (the UK average is 5 day’s absence per year), the employee’s holiday (20-25 days), employers’ National Insurance contribution (12%), pension, health insurance, training and career development, plus any other benefits an employee might expect (mobile phone, laptop, company car etc). You’re also not paying an upfront recruitment agency fee for hiring an employee.

The decision between a permanent person and a contractor may be based on reasons other than cost. If you want to build a team or company culture, or have the same staff for a long term, you’re more likely to want to want an employee. If work comes in peaks and troughs, where there may not be enough work in some periods, you’re more likely to want a contractor. You may be able to get a contractor in more quickly than hiring someone on a permanent basis (where there may be a time-consuming recruitment process). Each have their merits.

How do you make the decision between the two options? You can share your thoughts below.

Flickr image: LOLren

New Technical Author vacancies

#4138 Technical Author/API Documentation Writer, City of London, £37K-£40K DOE

This is an opportunity to join a technical writing team within a fast-growing, independent software company. Our client develops Web-based financial trading software for the world’s largest financial institutions. They have an immediate vacancy for a Technical Author with a passion for technical communication.

#4137 Technical Author, Cambridge, £28K-£40K DOE

One of the most successful software companies in Cambridge is looking to recruit a Technical Author to join its team. The company has grown rapidly over recent years, based on a philosophy of hiring great people, providing an enjoyable working culture and environment, and building great products.

#4136 Lead Technical Author Leeds/Rhubarb Triangle Circa £30K

Our client, based south of Leeds, is the leading supplier of document management software to the NHS, and it has plans to grow within the UK and internationally. It is looking to recruit a Lead Technical Author.

This is a great opportunity to lead their documentation and video strategy, along with the opportunities that result from working for a growing business.

New Technical Author vacancy – Cambridge, £28K-£40K DOE

One of the most successful software companies in Cambridge is looking to recruit a Technical Author to join its team. The company has grown rapidly over recent years, based on a philosophy of hiring great people, providing an enjoyable working culture and environment, and building great products.

For more information, see #4137 Technical Author, Cambridge, £28K-£40K DOE