How old are your readers?

In his newsletter last week, internet psychologist Graham Jones  mentioned research that had looked into what makes some web content more shareable than others.

The researchers had analysed articles on Medium, and found there were several key factors.

One was the length of the content – around 1,800 words ( approximately 7 minutes reading time).

Another was the the “reading age”.

Graham wrote:

“The study on Medium shows that the content that gains the most engagement has a reading age of 11.”

In terms of their reading age, how old are your readers?

Graham also said:

“Typically for most business websites that I examine the reading age averages around 17 years…The Times newspaper has a reading age of 12; the Daily Mail has a reading age of 10. The reading age of the script on the 10 o’clock news is about ten as well. It is no coincidence that the world’s most popular media have low reading ages. Whatever you might think of the BBC or the Times or CNN or your favourite magazine, one thing unites them all – low reading ages. Most websites have language which is far too complicated.”

Of course, it’s not always easy to describe complicated things using simple language. We may need to describe tiny differences and modalities. However, we should aim for clear and simple language as often as possible.

A related factor was the number of words in a sentence. Graham reported the study found that the most shared content was that which had sentences that were between 12 and 15 words. This matches with best practice at places such as the Government Digital Service, where the aim is to write 11 words per sentence.

Even if your readers are much, much older than eleven, it may be a good idea to pretend they are.

Research into how API documentation fails

There isn’t a great deal of research into API documentation, and the factors that make API content good or bad. Here’s some of the papers we’ve found so far:

How API documentation fails

How API documentation can be effective and useful

Do you know of any others?

Revisiting “How many technical writers should we have in our organisation?”

We received an email today:

Having read your paper titled ‘How many technical writers should we have in our organisation?’,  I was wondering if you ever did the follow up the final results from you survey as mentioned in the paper and if they are available?

This refers to an article we wrote in 2003, where we looked at research on ‘standard’ ratios between developers and Technical Authors. We said we’d Cherryleaf would be producing a report on the final results from our survey this summer, but we didn’t obtain any new information that needed to be added to our preliminary report.

Have things changed since 2003?

There are some software tools for automating the creation of some API documentation, and organisations that have moved from Microsoft Word to a component-based content management system are likely to need to spend less time on the “look and feel” and formatting of the published content. However, we doubt these have had a major effect on the productivity of technical communicators.

An alternative way to determine the ratio

There is another way to look at the ratio of technical communicators to programmers – one we didn’t discuss in our original report. You could use the job sites to look at the total number of vacancies for programmers and the total number of technical communicators, and generate a rough-and-ready ratio that way.

It’s a rough estimate, because the job sites contain duplicate vacancies (a job can be advertised by more than one agency) and job titles can vary.

Looking at the site today, there are currently 134 vacancies for Technical Authors and 761 vacancies for Programmers. That suggests a ratio of 17.6% , or roughly one in six technical communicators to programmers.

What do you think?

Please share your comments below.

The four words that account for 19 minutes of a typical Technical Communicator’s day

Peter Norvig has some interesting statistics on word frequency in the English language. It turns out that four words – the, of, and, to – account for 16.94% of the words we write.

In field of technical communication, Technical Authors typically spend 50% of their time writing and the rest on researching, planning etc. If we adjust for the fact that these four common words are half the length of an average word in English, that means Technical Authors spend an average of 19 minutes every day typing those four words. In a 37.5 hour week, that amounts to 1 hour and 35 mins.

New University of Oxford research shows surprisingly high numbers of out-of-control technology projects

What the customer wanted cartoonResearch conducted by two Oxford academics (Why Your IT Project May Be RiskierThan You Think) has suggested that the private sector has almost as much difficulty managing big software projects as the public sector. It also indicated that some types of projects have put companies’ survival at risk.

Whereas government departments can experience almost permanent revolution, private sector processes, in general, remain fairly stable. So it’s depressing to learn one in six of the projects they studied was a “black swan” – with a cost overruns of 200%.

The causes include: technology that doesn’t work, the difficulty in accommodating the exception cases, managing large teams, changes to the scope of the project, dealing with legacy systems, changes in legislation, and failing to build a system that meets the users’ requirements.

The researchers recommend breaking projects into smaller, more manageable units and using the best possible forecasting techniques.

There’s an additional problem: systems that work technically can still fail. If the user does not understand how to use the system, or if they don’t understand the benefits of using it, your “successful” system can end up under-used. User Assistance (online Help, Getting Started guides, screencasts and so on) mustn’t be forgotten. It’s one of those final steps in a truly successful project.

The over optimistic user

On Dara O’Brien’s Science Club (BBC 2) this week, neuroscientist Dr Tali Sharot explained “Optimism Bias”, suggesting that our brains may be hard-wired to look on the bright side.

Here is her TED presentation on the Optimism Bias:

Nearly everyone is optimistic they will never get divorced, and they are an above average driver, when statistically that’s just not possible. It seems reasonable to infer that users of software are  also over optimistic, believing they are an average or above average user in their ability to use an application.

This has an implication for those developing user documentation and training. It seems likely that most people will believe they don’t need to read the documentation (or receive training) when they actually do.

What word clouds can tell you about your user guides

Someday, some clever person will do a statistical analysis of the frequency of words contained in different user guides to help us gain a better understanding of how to make the best user guide possible. In the meantime, we can use Wordle to give us a glimpse into a few user manuals.

Wordle generates “word clouds” from text that you provide. The clouds give greater prominence to words that appear more frequently in the source text. To get it to analyse a complete guide, your documentation needs to be online and contain a RSS feed. Here are some Word clouds for three companies that provide RSS feeds to their documentation:

Autodesk (Autocad)


Atlassian (Confluence)

What is surprising is the lack of commonality – very few words seem to be popular across the three examples.