If you’ve read the technical writing blogs and magazines, you’ll have noticed a growing interest in new approaches to technical communication – asking whether all of the tried-and-tested writing methods from past decades still make sense today.
In this course, you’ll find out how Technical Authors in leading companies are now applying techniques from other disciplines (such as psychology, copywriting, usability and elearning) into the information they create. The course has been designed to be independent of any particular authoring tool, and to work in both a structured and unstructured authoring environment.
If you want to discover new approaches to technical writing, this one-day, hands-on advanced workshop is right for you.
To start with, we’ll be offering this course on-site or in-house (i.e. at our training centre in Central London), with public courses following later on. As an on-site course, the exercises can be based around your existing content.
It’s not Black Friday, but perhaps we can call it Grey Tuesday. As part of Cherryleaf’s 10th anniversary celebrations, we’ve created five 25% discount coupons for our popular Technical Author basic/induction online training course. The first five customers to use coupon code 09E2C3D43D when ordering the online course, will receive the 25% discount.
In Data Quality Pro Journal, Dylan Jones interviews Ellis Pratt, Director at Cherryleaf, about how to improve Healthcare data quality through policy and procedure management. According to Dylan,
“One of the single most common root-causes of poor information quality is outdated documentation and a lack of governance in the way policies and procedures are managed. Nowhere is this more critical than in the healthcare sector.”
Ellis shares a range of practical techniques and methods to help improve policy and procedure documentation within the healthcare sector.
In this week’s Autocar magazine, Chris Goodwin bemoans the fact that Daimler AG has taken the romance out of its owner’s handbooks.
He refers to the handbooks for Mercedes cars built in the 1980s, and how they congratulated the owner on their wise decision to purchase an expensive, high quality car:
“We can design away the need for a user manual and online Help”
The idea of a product that totally is intuitive to use, the product that sells itself, sounds terribly attractive. Often these are called commodities, and consumers tend to go for the cheapest one, or the one with the best brand image.
There are situations where good intuitive design can sell successfully, and the Apple iPad is probably the most well known example. However, even iPad users seek Help and want user guides.
As we mentioned in previous posts, HTML5 enables Technical Authors and courseware developers to synchronize different media. One of the key areas where this can be applied is in eLearning, where users are now able to toggle between text-based content and video tutorials.
As a consequence, Technical Communicators will need to decide which form of text to provide with the video.
Should it be:
a transcript, faithfully documenting every word that was said in the video?;
an edited, but still conversational, version?; or
text written in the minimalist writing style we normally see in User Guides and Help files?
Let’s look at the case for and against providing an exact copy of what was said in the recording.
The case against a transcript
The manner in which we speak and the way we write are often significantly different. Hugh Lupton, from The Company of Storytellers, once said:
It’s a very different journey from the eye to the mind as from the ear to the mind.
In oracy, the artifices of the speech are very important. These are what Marie Shedlock called “the mechanical devices by which we endeavor to attract and hold the attention of the audience.” They are the gestures, the pauses, the repeated phrases that a good presenter will use.
For example, in this performance by Daniel Morden and Hugh Lupton, Daniel repeats “not for you” as a way of keeping the audience engaged (from 0:13):
If we make a transcript, we retain these artifices in the written word. Instead of improving the comprehension, when published in written form, they can make it harder for the user to understand. For example, if the user searches for a key word or phrase, the repetition of those key phrases by the speaker is going to make it harder for the user to find the right instance.
The case for a transcript
Unlike the storytelling examples above, eLearning is rarely delivered in audio form only. In most cases, the presenter and the audience has a shared visual image to view. This helps ensure there is shared understanding.
A transcript gives a true representation of what the presenter said.
If a user remembers a key phrase or word in the presentation, then they may want to search for that moment to replay it. If the text has been edited, or is significantly different, then that phrase may have been omitted.
Which approach should you take?
We suspect over time that the text provided in synchronized elearning courses will follow the minimalist style that works in User guides and Online Help, where the subject matter is technical in nature. A more conversational tone may work where the material is non-technical (e.g. easy to use consumer goods), providing an overview, or where there isn’t the time to do anything more than provide a transcript.
One of the challenges for organisations moving to a new content management system for their user documentation is selecting an authoring tool that is:
powerful enough, and
can be used by non-Technical Authors as well as the professional Technical Authors.
Many organisations want staff, such as developers, to be able to add content to the system directly – without having to pass it over to the Technical Publications department. The difficulty lies in that many tools for authoring in DITA and other XML schemas are daunting to those unfamiliar with the underlying principles of DITA and structured content. It’s even more challenging if you’re someone who is only going to write content occasionally.
One approach is to create templates, with defined fields that need to be filled in. Another is to get staff to write in Word, again in conjunction with a template, import the text into the content management system and then map metadata and other semantic information to the content at that stage.
Is it an unsurmountable problem? Should we just accept that writing semi-structured XHTML content (such as wiki-based content or WordPress-like authoring environments) is a better compromise? What you lose in modularity, you gain in having an easy-to-use authoring environment. Alternatively, do we need to recognize we’ll always need specialists who can convert text into the appropriate format - the equivalent of the typing pool or typesetters?
It has bearing on the role and value of Technical Authors. Is it their main value in writing skills, information management skills, editing skills or in using a specialist tool? If the organisation believes “everyone can write well”, then is their value in using software that’s complex and tricky to use?
Matthew Syed is a British sports journalist and former three times Commonwealth Games gold medallist, who has been investigating what is needed to make people excellent at doing any task involving complexity.
He argues that natural talent, your genes, are far less important than many people think. What’s important is practising what you can’t quite do. He argues we grow if we test our limitations, because our body adapts.
So what on earth does that have to do with developing software and Technical Authors? Syed argues there are two opposing views regarding success:
One “school” believes talent is what makes success. This means that if you fail, you believe it’s because you don’t have enough talent. Therefore, you’re likely to give up.
The other “school” believes success is all about practice – the quantity of practice, the quality of teaching and the willingness to test our limitations. This means that if you fail, you believe you can succeed with more perseverance and effort. It’s an opportunity to adapt and grow.
I would argue the whole philosophy of User Assistance is based around the belief that talent is all about practice. It’s easy to forget that others may think it’s all about talent – your developers may believe some users fail because they are stupid, and some of your users may believe they’re just not good enough to succeed. It’s worth checking what they believe.
Another implication is that we should provide assistance and guidance to users as they are doing the task. We should try to avoid interrupting their flow. This suggests providing Help and advice within the application screens themselves.
Thirdly, we should praise people for their effort rather than for their talent.
With more and more people using the iPad and other tablets for reading technical documentation, this workshop looks at how tablets can be used by organisations to design and deliver technical documents and other forms of User Assistance.
The course will be held in Central London on Thursday 31 May 2012, 9.30am-12.30pm.
You do not need to have a tablet to attend this course, or have previous knowledge of using a tablet.
This course is aimed at Technical Authors and others developing technical documentation and other forms of Help for users.