The Government Digital Service has published an interesting guide on writing copy for User Interfaces and transactional interfaces:
We spotted an interesting statement by the “Father of Behaviour Design”, BJ Fogg:
“For somebody to do something – whether it’s buying a car, checking an email, or doing 20 press-ups – three things must happen at once.
The person must want to do it, they must be able to, and they must be prompted to do it.
A trigger – the prompt for the action – is effective only when the person is highly motivated, or the task is very easy. If the task is hard, people end up frustrated; if they’re not motivated, they get annoyed.”
See Ian Leslie’s article “The scientists who make apps addictive“.
If we want users to read Help text instead of calling the support line, then we maybe we need to meet those three criteria.
We can assume the user is motivated to fix their problem.
We can write instructions that are clear enough to make them able to solve the problem.
Where some applications fall down is they don’t prompt the user to read the online Help. The link to the Help text is often tucked away in the right hand corner of the screen.
Instead, we could put some of the Help text into the User Interface or the dialog screens, and we could prompt the user to follow a link to more information. Doing this could get users to read the online Help rather than call support.
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.
Following on from James Mathewson’s presentation at Content Strategy 17, we’ve been reflecting on Cherryleaf’s main website, and the improvements we could make to it. One thing we have started to do is reduce the reading age for the content. Reading age measures are also, in effect, readability measures. So any improvements also benefit people with a high reading age.
There are a number of factors that affect the readability of a page.
One is using the active voice. In our case, there were only a few sentences using the passive voice that we needed to change.
Another is to reduce the sentence length. We found we had many long sentences. We’ve split those into two, shorter, sentences.
We’re still being marked down in the readability scores for using “difficult words”. This is harder to fix, as we need to describe technical subjects. We also don’t use many transition words in sentences. This is probably a symptom of writing short Help topics, where transitions are less common.
We’ve also updated the look and feel for the main site (and for this blog), and we made some changes in order to reduce the number of clicks needed to get to information. This is a work in progress. We hope you find the site easier to use.
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”.
“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.
A technical communicator’s lot is usually to create content for helping users, and, if they are lucky, do some user testing of it in order to make future improvements. It is not that common for them to be able to look at the bigger picture and think about how the user gets to that information in the first place.
Customer Journey Mapping is an extremely useful way to understand and improve the customer experience. It involves creating a document (often a spreadsheet) that describes the user experience from their perspective. It can record each point at which interact with your service or product, the quality of that experience, and what happens next.
Customer Journey Mapping is something we carried out recently for a client, and it was a topic that came up at the TCUK 2016 conference, in the presentations by both Sarah Richards and Simon Anstey.
Our client is a start up Software as a Service company that is growing rapidly. They are creating new products, gaining new customers, and they are having to face all the challenges that brings. We mapped the journey of a user who wanted to install the product. We used a spreadsheet to record each stage and any issues or problems that users came across. The user began at the company’s website, where there were various links for installing the application, including instructions on how to do that. It revealed there was confusion between the product available on Amazon Web Services and the product clients install in-house. This was because the same, or similar, terms were used to describe the products themselves and the features contained within the products. On some pages, users were directed to the Support desk system and the articles contained there. On other pages, they were directed to PDFs, which described how to install the previous version of the product. There were also a few pages that took them to the online Help system. The Customer Journey map made it easy to change the website so it directs users to the single place for information, and to remove duplicate, and out of date, information.
In Sarah Richards’s presentation at TCUK 2016, she described the approach the Government Digital Service took when they developed the Gov.uk. website. GDS removed content that didn’t address those needs, and consolidated hundreds of government websites into the single gov.uk site. They kept 45,000 pages, and culled 92,000. This process started with user needs, and were designed around those customer journeys.
Sarah’s TCUK 2016 slides aren’t available yet, but here is a similar presentation she gave at another conference:
In Simon Anstey’s (of SAP) presentation, on eliminating Support tickets, he described how he looked at the customer journey for raising a Support ticket, and collaborated with SAP’s customer support team to improve the documentation, and links to useful information, for some critical products. This stemmed the flow of support tickets. They estimated the resultant cost savings and started gaining management’s interest. This activity meant they could show what value documentation was adding.
Customer Journey Mapping can be revelatory in revealing issues that may not be obvious at first glance.
Here’s some examples from Munich of what might seem to obvious and common sense to the one audience, but not to others.
Traffic lights that have four lights, with the symbols –, O, I and K:
Pedestrian crossing lights that have two people instead of one:
The second set of lights is still comprehendible (hold the hand of the person next to you, whilst you’re waiting to cross the road 😉 ), but the first set didn’t make sense to even the (non-Bavarian) German members of our party.
Mozilla is an organisation that always seems to be doing innovative things with their documentation. One of the experimental functions it has introduced to its Kuma wiki platform for the Mozilla Developer Network (MDN) documentation is an experimental PUT API that makes it possible to create and update articles remotely.
Mozilla suggests a number of ways it can be used:
You can create a page for your project and update content in certain sections from automated build, testing, and deployment scripts. This can help you keep your community up to date with your project’s progress.
If your project offers documentation alongside source code, you can push HTML renderings into a subsection of MDN. This lets you maintain docs in a way that’s appropriate for your team’s workflow, while still contributing to MDN and allowing localizers to translate the content.
Fro example, Mozilla’s programmers are able to write scripts that automatically generate articles based on contents of header files they’re creating. The API uses HTTP, which means software engineers (and other writers) effectively have the freedom to use the application environment and libraries of their own choice.
Kuma itself is an open source platform written by Mozilla in Python, using the Django framework. Contributors can fork the Kuma repository on Github, make changes to the content, and push the revised content back to the wiki.
It will be interesting to see if this succeeds, and if this type of platform extends further out than its use for developer documentation.