New training course – Writing skills for developers

Today, we’ve released our latest training course – Writing skills for developers. The course teaches developers the key skills of technical writing for software user documentation.

writing techniques web page

Although it would be better for a professional technical communicator to write the end user documentation, for some organisations, this isn’t always possible.

It is for developers who:

  • Need a solid understanding of the fundamentals of technical writing
  • Want to communicate more clearly and effectively
  • What to know how little, or how much, they should write
  • Want people to answer their own Support questions

The course comprises 14 modules in total, which delegates can complete at your own pace. The course modules are delivered over the Web in small, manageable video presentations. The course handouts and exercises are downloadable as Word or PDF files.

We can also deliver this course as a classroom course for development teams.

For more information, see: Writing skills for developers training course.

Using Hemingway on our website

Last week, we used the Hemingway app to highlight any unclear pages on our main website. The app highlighted four pages where we’d used the passive voice or very long sentences.

The first inclination was to think our readers are cleverer, our content is more technical, it’s not possible to rewrite those parts. We found, of course, we could rewrite them. We decided to write them in the same way we’d write user documentation. We found those passages were much clearer, as a result. A lesson learnt.

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.

Americanisms and Britishisms

There are user documentation projects where we are asked to write in American English instead of British English, and generally this is a pretty straightforward exercise for us. However, when I speak at conferences in the USA, delegates sometimes ask me afterwards what I meant by a particular expression. For example, I was recently asked what I meant by “round the houses” and “cheesed off“.

There are a large number of subtle differences between the two versions of English, which has led to a number of very interesting blogs on this subject. In particular, Dr. Lynne Murphy’s Separated by a common language and Professor Ben Yagoda’s Not One-Off Britishisms blogs provide a fascinating insight into how words and expressions gain popularity. The Language Log is another blog worth reading.

If the move to a more conversational approach to technical writing grows in popularity, we may see these differences becoming a bigger factor in localis(z)ing to American or British English.

Cherryleaf presentation on creating effective content

Just a reminder that Cherryleaf’s Ellis Pratt will be speaking at the Institute of Directors’ June 2015 Members Masterclass on “The written word – creating effective content”.

The written word is one of the key ways we communicate with others. Whether we’re telling or selling, it’s important we get our message across. Unfortunately, many people find writing time consuming, and it can often be difficult to get started on a new document.

In this session, we’ll look at some of the most effective techniques for creating the types of content created in today’s business world. You’ll discover some of the approaches used by professional technical communicators, copywriters and report writers.

Some of the issues we’ll look at include:

  • Clarity and persuasiveness
  • Getting started and organising your thoughts
  • How to structure documents
  • Getting to the point and being concise

This session is ideal for managers, engineers and other professionals interested in effective approaches to communicating more clearly and effectively in writing.

The IoD invites IoD Members and non-members to share their expertise and knowledge with other members. It will be held at 116 Pall Mall, London, on the 2nd June (18:00 – 21:00).

See:

The written word – creating effective content.

Why business writing is so difficult

“Everyone is taught to write at school, so surely everyone can write in business?”

Although the quotation above would seem to make sense, the reality is that many people find it hard to write in a business context. They struggle to write clearly, and it can take them ages to produce a piece of content.

It’s not their fault. What we’re taught at school is how to write narratives, that is stories or articles. We’re also taught to argue a case – to use rhetoric to build to a conclusion. We’re taught writing to persuade and writing to entertain.

In the world of business, we often need different forms of writing. We’re often writing to inform or writing to instruct.

In these situations, people want to know what they should and shouldn’t be doing, and get on with their jobs. They want the important information at the beginning, rather than the end. They want to scan and hunt for the information relevant to them, rather than always having to read everything from beginning to end.

Many people haven’t been taught how to write to inform or to instruct, and that’s why many people find business writing so difficult.

Institute of Directors masterclass on: The written word – creating effective content

Cherryleaf’s Ellis Pratt will be speaking at the Institute of Directors’ June 2015 Members Masterclass on “The written word – creating effective content”.

IOD building

The written word is one of the key ways we communicate with others. Whether we’re telling or selling, it’s important we get our message across. Unfortunately, many people find writing time consuming, and it can often be difficult to get started on a new document.

In this session, we’ll look at some of the most effective techniques for creating the types of content created in today’s business world. You’ll discover some of the approaches used by professional technical communicators, copywriters and report writers.

Some of the issues we’ll look at include:

  • Clarity and persuasiveness
  • Getting started and organising your thoughts
  • How to structure documents
  • Getting to the point and being concise

This session is ideal for managers, engineers and other professionals interested in effective approaches to communicating more clearly and effectively in writing.

The IoD invites IoD Members and non-members to share their expertise and knowledge with other members. It will be held at 116 Pall Mall, London, on the 2nd June (18:00 – 21:00).

See:

The written word – creating effective content.