This is a blog post about my ‘dev day’
For the unitiated, a ‘dev day’ is:
… basically a learning day for educators or business professionals.
http://www.wisegeek.com/what-is-a-professional-development-day.html
Yep, it is what it is, so for a documentation professional that would entail a learning day for improving documentation, right? Read on to see what I learnt, and how I intend to make Caplin documentation that much better!
I skipped typical dev day rituals of attending public conferences and workshops, and instead I dug up some old notes from previous workshops I’d attended – stuff I’d previously glossed over, but didn’t find the time to reflect on.
Just for the record, all learning material used during this dev day and shared throughout this blog originated from Cherryleaf’s Advanced Writing Course managed by Mr. Ellis Pratt.
After taking a spin through the material, I reflected on three techniques that could help improve technical documentation
Documentation technique #1
This one’s an oldie. Here, I explored the traditional approach to technical writing that involves information mapping. This is basically a way of laying out information similar to a glossary, where the information displayed is very succinct, minimal and highly accurate. The information is easy to understand and easy to search through, and there’s lots of tables with neatly aligned stuff.
This approach is still in use today as it’s most effective for conveying information when it matters most. For example if you wanted to document a technical manual for say a Jet aircraft engine, or even a spacecraft – this is definitely the approach you’d want to use. Here the reader will need very clear-cut instructions, and want to be able to find exactly what their looking for without sifting through waffle.
However, this style of documentation can come across as quite boring… I mean who reads the manual any more, eh?
Some of the strengths and weaknesses of this approach can be summed up to better understand how and when it should be used, some of these include:
| Strength | Weakness |
| Succinct (i.e. to the point) | Monotonous – The repetitive tone can get boring real quick. |
| Orderly – Information is easy to navigate | Not engaging – A reader needs to be engaged with by using a more conversational tone. You want to be able to adapt to peoples moods. |
| Organised – Information is easily searchable | Verbose – Information layout is key to holding readers interest, monolith text can be discouraging. |
| Accurate – Information is minimal, only what you need to know is displayed | Minimal – only what is absolutely important to know is documented, leaving little room for background or context. |
How can it apply at Caplin?
Reflecting on this style of writing, I wanted to know where it could be best applied here at Caplin. Currently, the style we use for some technical overviews is conversational using an engaging style of writing. This way, things are explained as if I were right there next to you having a chat. This is appealing as opposed to a repetitive, mundane tone, which can get boring real quick and might not engage the user on a supportive/ personal level.
Thus I think the traditional approach can be reserved for deployment instructions or installation material that is known to be essential or critical in nature, such as installing a complex system for the first time that might take longer than say, 30 minutes on average. A conversational tone can be better used when providing high level overviews.
The traditional approach can also be used for the following:
- Tourism information
- Product Catalogues
- Health and Safety instructions (Obvious one, who wants a casual, conversational tone here!?)
Use the traditional technical writing style when you know that your reader will want the information as quickly and accurately as possible to meet their immediate needs, or to solve a problem right now.
Documentation technique #2
Yeah this one’s kind of new… and it’s all about the human psyche! Here we’re exploring a psychological concept called Social Proof – hmm documentation is deeper than you thought ay? To cut a long story short, you will find that in a social setting “People will do things that they see other people are doing” – Robert Cialdini. See my blog ‘New ways to write better documentation’ for some more insight on this, as well as a funny video.
With documentation, Social Proof can be applied to the way we deliver help to users when using online mediums such as FAQs, Forums etc.
You want answers to the same questions other people are asking…
Have you ever wanted the answer to a question that may have been asked before? Perhaps it was related to a specific product or service even..? So you stroll online, land on a page related to the product in question and BOOM! You found the frequently asked questions page – you are very likely to find your answer here. This is effective online help as minds are easily put to rest when the answers to what most people’s questions are made easily accessible.
The same can be done for solving any product or service related issues. Ever wanted to solve a problem you thought was pretty common, or perhaps it’s a bit more specific? What you need is a forum – you have most probably visited one before, and they are quite useful more often than not. These forums will have what are known as a ‘sticky page’ – these are pages permanently marked on the forum’s navigation page that will provide commonly sought after information, addressing the most general of queries. Creating a sticky page can require gathering information already on the forum, based on what forum members have previously asked or shared.
How can it apply at Caplin?
As we said, with an FAQ page you can appeal to the wider audience, with a forum you can provide a platform to explore common problems as well as more specific issues. Caplin’s customer base represents a number of technical developers that use our various products and tools. The scenario is that we hand over a piece of software to a client, they then turn around to us and say, ‘Great, can it do X and how is Y used?’ If we can identify frequently asked questions by all these developers, we can instantly provide the answers without pointing them to a library of documentation. Overall this tells others that this particular page is popular, so come take a look and you’re likely to find what you need – this is the idea behind Social Proof.
The FAQ will need to be maintained as the scope of products change, but for the most part it’s a quick and easy solution for everyone, limited as it may be.
A forum on the other hand is far more complicated, as it requires infrastructure as well as terms and conditions among other things. It is costly to manage in both time and resources, but in the long run can provide a strong community that users can turn to in times of need. Caplin indeed have a ton of documentation, as well as a Support helpdesk, having our own forum may help solve questions that are usually beyond the usual scope, or serve as a database for previously solved problems.
So where else can Social Proof be used?
Highest rated pages – These could exist on a forum, or as part of your existing documentation structure. If you have documentation that is hosted online across a series of webpages, a star-based rating system can indicate how useful the page is.
Questions currently being asked – This is a pretty common one where the main navigation page on a product website may have a section entitled ‘Latest’ or ‘What’s new’. Here you can include pretty much all the latest docs you’ve been working on as part of a recent product release – users are likely to be searching for product documentation around release time.
Documentation technique #3
Oldie, but it’s being re-invented! Let’s talk about Priming. With documentation, Priming can be used as a way to influence thought processes and behaviour while reading words. The idea is pretty simple – for example, if you’re writing a user guide you could increase the confidence for the user before they attempt to follow any instructions. This can be done with phrases like ‘Once you follow these five easy steps, you can sit back and relax’ or ‘this guide is relatively short, and you should be up and running very soon’.
The general theme that we are trying to express here is that we are on the user’s side, we want to help them. By saying a guide takes five minutes to complete from the onset, a user might see this as a record to break, and proceed with motivation. Priming helps to encourage, motivate and reassure the user before they follow instructions.
Photo credit: Vic (Used under the Creative Commons Attribution License.)
How can we use more of this at Caplin?
I say more as we already employ such methods to instil confidence with our users. But I’m sure we can do more – for instance priming doesn’t just need to precede a set of instructions, we can add a rewarding statement once they have finished, like ‘Good job’, ‘Well done!’.
Another method we could use is, prior to outlining the main instruction set of a user guide, what if we threw some basic exercises at the user first? Some related instructions that are dead easy, just to give the user a taste for success first? Then as they begin the real instructions, they might have that added boost and endurance to see it through.
Final thoughts
The techniques explored during this dev day can serve as a starting point in improving the way we communicate with our target audiences. It’s up to you as an individual to see how and when they should be applied. Consider the typical applications for each technique, and have a think of where you could use it in your day-to-day writing activities. I’m confident that if used correctly, these techniques can benefit both the writer and the reader in equal amounts.
With this being my first dev day, it turned out to be very enjoyable. I learnt a good deal, and there were no exams – which made it even more fun!
I look forward to my next dev day, and making Caplin documentation that much better – every little helps you know. Until then, adios and happy writing!