New ways to write better documentationon Feb 14, 2014 in Software Development Process, Work/Life by Adam Saleh
After a thought-provoking experience of an advanced writing course at the end of last year, I thought I’d share what I learned. Stay tuned for some fascinating videos, a view on how Caplin is keeping up with the latest communication trends, and even some cool writing tips you can start applying today!
Held at the Institute of Mechanical Engineers in the heart of Westminster, the advanced course is run by Cherryleaf’s highly revered director, Mr Ellis Pratt. Lasting around 6 hours with ample time for lunch and quick breaks, the course was well-structured and straight to the point.
Having never attended similar courses or undergone any formal training myself, I found the whole experience well-paced and informative with the right degree of intensity, despite the advanced label. In attendance, we had a few senior writers varying in backgrounds and fields, most of which having many years of experience, hoping to polish their skill sets and learn some exciting new techniques!
Unfolding like a short story; the course introduction provided a succinct insight into the history of technical communication, looking at traditional approaches from the 50s-80s, past trends and new writing styles that are emerging now.
The traditional approach to technical writing
The introduction went on to describe how in the past, the focus had always been on the traditional model of a person failing in something, and so we tell them what to do, in the briefest possible manner.
Information would thus be presented in a style that implements information mapping. This type of structure resembles a glossary, where explanations are succinct, to the point, and quite mundane.
This structure presents information in an easy to find way, that’s both understandable and accurate.
So why is the traditional model no longer popular with audiences today…?
Well, the information is not very maintainable, less conversational, and can come across as quite monotonous and verbose. So it doesn’t really adapt to peoples moods, or actively engage the reader in any way.
Change is happening!
People tend to find the traditional style boring to the eye, and is one of the reasons people tend to neglect large help manuals.
However, the traditional model may still be relevant for certain criteria’s such as safety manuals or health and safety guides; where the user will need an affirmative tone to adhere to when following instructions. For the most part, this model’s approach is outdated by today’s standards where technology is changing rapidly, and sociability is taking precedence.
People prefer an active voice, a tone which sounds more like a human being who sympathises with your needs as oppose to a passive, robotic style that doesn’t do much to make you feel engaged or interacted with on a supportive level.
New ways of delivering help to users
Many of you may be familiar with the current support mediums available whenever you wish to find help. Online help forums are vastly popular, especially here at Caplin where internal staff frequently visit online forums to find any sort of help relating to a specific problem that may or may not have existed before. Other support mediums include tool tips, FAQs Wizards etc. all of which have weaknesses and strengths, but in some shape or form provide a more sympathetic, engaging dialogue to users.
The course outlined some interesting psychological concepts and techniques that have proven impacts on user behavior, a prime example is social proof, take a look at this video:
This video demonstrates the idea behind social proof whereby people tend to do things that they see other people doing.
‘But how does this factor in with written communication?’, I hear you thinking… well from a sales point of view it makes for a powerful persuasion tool. Have you ever come a cross banners, brochures or adverts for products, perhaps a software product.. where a label such as 97% satisfaction guaranteed is printed on the front, or ‘this is our most popular deal’..?
It’s techniques like this, that are already in use by various corporations, that delve into the human psyche, if one reads such a label they may ponder, ‘ well if that many people found the product satisfying maybe I should go ahead make a purchase?
I am sure you can think of numerous other examples of where some degree of social proof has been implemented. Here are some other examples of social proof delivery methods across different mediums, not just sales or advertising:
- Highest rated pages – perhaps in a help forum, most popular pages visited by users indicating a commonly used solution
- FAQs – could be relating on particular product on a site page, where the most common questions here have been asked by previous users.
Alongside social proofing we learnt about priming, another fascinating technique stemming from the realms of psychology. Priming is based on the notion of influencing emotions and behavior through the act of activating concepts in memory to trigger subsequent behavior.
A short video describing the effects of priming through words and advertising from some big name corporations:
A technical author should hope to increase the success rate at which a user can effectively and accurately follow instructions in a user guide. Priming can aid this success rate, by inducing an additional sense of confidence before implementing a set of instructions.
As an example of priming, you might start of a fairly basic installation tutorial for a piece of software or hardware with the opening words: ”This installation is easy, on average it takes just five minutes to complete!..”. In doing so, you’ve helped to instill a sense of competitiveness and enthusiasm with the end-user, triggering the conception of a straightforward, hassle-free task where the user can even feel motivated to beat the five minute average set up time.
If you have more confidence you are more likely to take a stab at a complicated set of instructions. Stating the average time to complete a task helps make the user feel at ease by knowing how much time and effort is required from the onset.
I’ll pick up on this in my next post…