Google’s Riona MacNamara presented at the Write The Docs North America conference on “Documentation, Disrupted: How Two Technical Writers Changed Google Engineering Culture“. In the video of the presentation below, Riona explains how she worked with a small team of writers and engineers to build a documentation platform in six months that is becoming a part of the standard Google engineering workflow.
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.
In the UK, every building, apart from private single dwellings, needs to be assessed for fire risk every three years. To do this, a fire risk assessor will assess the building and write a report on their findings and recommendations. For offices, these reports can be 30 pages long, and it can take an assessor a full day to complete the report.
We’ve been working with a fire risk assessment firm to create a system for them that generates these reports in less time and in a more consistent way. Like many organisations, they’ve been using Microsoft Word to write the reports, and this can lead to a wide variation in the way the reports are presented.
Cherryleaf has been developing a report generator for them that significantly reduces the time needed to produce their reports – they believe they can reduce the time needed from a day to an hour – and, this week, they’ve started to print out the assessments they’ve been writing.
So what did we create for them?
There were a number of potential software applications we could have used (for example, Author-it, Mindtouch and Confluence), but the best fit for this client was Confluence. Within this application, we created a master report ‘boilerplate’ that contained all the key information that should go into a fire risk assessment. This master boilerplate ensures there are no omissions in each report.
On the individual pages within the report, there are numerous drop-down sentences and blank text boxes for the assessors to choose. There are also ‘variables’, for chunks of information that need to appear in more than one place in the report – they are embedded in appropriate paragraphs. If you change the information contained in the variable, then this change is implemented at the appropriate places in the document.
The project has produced a number of challenges. For the client, they have been looking hard at the content that goes into an assessment report – and how to create a single report that satisfies the many different standards for fire risk assessments. For us, we’ve had to create a system that works for people who might not be very technically literate. For example, people who have never uploaded an image into a document before. We’ve also had to create something that’s very flexible – suitable for assessments of small buildings such as bandstands, bus shelters and suchlike, to big buildings such as tower blocks.
The proof of the pudding is in the eating, as they say, and we’ll soon be able to see how much time the client will save. The signs are looking good, and there’s likely to be further enhancements and developments to their system in the future.
At a rough estimate, there are 10 million buildings in the UK that need to be assessed for fire risk each year. If our system reduces, at a conservative estimate, the time needed to produce each report by 4 hours, then there’s the potential for it to save 40 million hours of writing time per year.
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:
What is surprising is the lack of commonality – very few words seem to be popular across the three examples.
As part of my prep for my presentation on user documentation as a more emotional experience for the user, I revisited this presentation by Kathy Sierra. This hasn’t ‘made the cut’ into my presentation due to lack of time, so I thought I’d post it here.
Here is a very innovative approach to providing a user guide, from Samsung :
According to Vitamin Design:
These books actually contain the phone. Each page reveals the elements of the phone in the right order, helping the user to set up the sim card, the battery and even slide the case onto the phone. The second book is the main manual – the phone actually slots into this and becomes the center of attention. Arrows point to the exact locations the user should press, avoiding confusion and eliminating the feeling of being lost in a menu.
It’s a interesting example of user documentation as an emotional experience. (Thanks tofor spotting this.)
If your business ever has to stand in front of a judge, you may regret believing the documentating of procedures didn’t matter.
When things go wrong, people ask “where’s it written down?” You’ll find them looking at what’s documented to see where the blame lies.
If it’s not written down, or if it’s unclear, then the eyes will be on the person whose job it was to make sure all the procedures, policies and guidance documents were up to scratch.
Cherryleaf can help by giving you the skilled resources you need to write clear and unambiguous information, in a timely and efficient way.
Contact us to find out more.
Here are some links to useful information on managing documentation projects:
If you need any advice or assistance in developing user documentation, you should contact Cherryleaf.