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 reed.co.uk 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)

Mindtouch

Atlassian (Confluence)


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

How many cuddles are you putting into your user guides?

From Fast Company:

“Neuroeconomist Paul Zak has discovered, for the first time, that social networking triggers the release of the generosity-trust chemical in our brains.

The essence of affection. The cuddle chemical. In other words, oxytocin. If these changes apply in the world of social media, the implications for business — for every brand, company, and marketer trying to understand the now intimately networked world — could be significant.”

So, how much oxytocin are you putting into your user guides?