Food for thought

Blogs are the big thing. Many companies now include a link to a blog as part of their website. The blog is used as a way of getting the company message across in a user-friendly way. The actual message is not as in-your-face as it would be using more traditional means, such as a concepts manual as part of a documentation set. So blogs might not be considered part of the technical writers armory at the moment, left to marketing gurus to spout forth their evangelical liturgy. But, as technical communicators we need to consider this newish form of information transfer and start to take it seriously, before it is not just the concepts manuals that will end up being commandeered by marketing.

When I started out in the field, there were few books on the subject, fewer courses in universities the world over and no websites to speak of and doesn’t that just age me – but I worry not, as explained in my previous post Too old to play football?. Now there are more courses than pips in a satsuma and the number of blogs preaching technical writing theory (like this one does), is ever-increasing.

As time goes on, if we want our documentation to influence our readership, then we must embrace new forms of communication, whether it be via social networking, smartphones or blogs. ePub formatting is now fairly standard as an output for documentation and adding comments and small pieces to Facebook, or promulgating updated material via Twitter or other social media is now common. But using a blog to describe a procedure or a feature in the product as a serious piece of technical writing doesn’t happen, unless it is a fix for some problem that support produce.

In the “good” old days recipes were transmitted by paper, in recipe books. Then there were a few television shows (who remembers Fanny Cradock or that galloping gourmet, Graham Kerr?). Now there are whole channels dedicated to cooking. True, there are still cookbooks being printed but often these come with a CD so you can see your favourite recipe being prepared.

Georg C. Lichtenberg, a German scientist and satirist said of food:

Food probably has a very great influence on the condition of men. Wine exercises a more visible influence, food does it more slowly but perhaps just as surely. Who knows if a well-prepared soup was not responsible for the pneumatic pump or a poor one for a war?

So the cookery world recognizes the influence it can have on the people populating this planet or ours. A quick search in Google for food blogs produced a staggering 1,120,000,000 entries while writing in general could muster only 799,000,000 and poor technical writing (combined with a search for technical communication) showed a poorly 25,540,000 entries.

As a profession we have to look at how our readership is absorbing and using the material it needs to work with our products. More and more I think it is going to be byte-sized pieces of information wrapped in a blog, or something similar.

It pays to be agile

It is not an information dirt track, it is an information highway, or even superhighway. And a highway means fast-moving. I spent my childhood in a world where Watch with Mother with Andy Pandy or the Flowerpot Men were the stars of children TV. Watching it now is liable to make you comatose. Those were the (good) old days where time wasn’t at the premium it is today. Bill and ben just wouldn’t cut it with todays children – not enough action! Not fast enough!

I don’t want to start a discussion about what lifestyle is better, since whatever the outcome of such a debate, the truth is we live in the here and now. Or did, since we’ve just moved on a bit more as I write these lines.

And as the world moves on, ever faster and faster, driven to a large extent, by the superhighway that now permeates every facet of our lives we, as the ones charged with explaining what is what, must move ever faster as well.

As a rule, we don’t sit in the driving seat, but if really lucky in the front passenger seat. If just lucky, in a back seat but more often than not in one of the trailing battered trucks that follow the developer supercar as he whizzes along the highway. And he is whizzing faster and faster.

Much development done today is done using the Agile methodology. In essence this is a style of development that hopes to get a product that answers the needs of the consumer out to market more quickly and efficiently than using previous methodologies.

Just as in traditional projects, Agile projects start with basic requirements gathering. Knowing the goals of your end users and project stakeholders is the necessary first step to any successful project. However, instead of trying to nail down all of the details up front, your goal in an Agile project is to capture just enough information to have a conversation with the customer at a later date.  You capture this information as short descriptions of the functionality in customer terms which you will flesh out shortly before development. Thus, you can avoid some of the overheads that are typical of projects where detailed requirements are gathered early, but often become invalid before the work begins.

During the development phase, there are short development cycles, between one and six weeks, with an end-product ready for release at the end of each cycle. The basic approach is to get-on and go. What is important is getting something out to the customer fast. If it only includes a subset of the customer requirements, this is OK – after all, it is better than nothing and in a few short weeks the customer will get another newer version with more features.

With this fast turnaround concept of development, including plenty of interaction between team members and between the teams and customers, there is little room for documentation. In fact the Agile manifesto states that the aim is to concentrate on working software rather than comprehensive documentation. Thus, face-to-face meetings and emails replace formal design documents and specs.

Since the product changes so rapidly, producing comprehensive user manuals, that becomes obsolete in the next cycle is a non-starter. Instead, the writer needs to concentrate on the bare necessities to ensure proper use of the product.

Minimalistic documentation has been around for years but now is its moment to shine!

Also, start thinking more and more out-of-the-box. For example, training materials can be merged with formal documentation or updates can be delivered via social media. The tweet “New folder feature in creation wizard: click Dir to specify folder.” becomes the latest documentation update. Nothing more is needed – no production, post-production, publishing, etc. A short tweet does the job!

Cut the verbiage. As George Orwell (of Animal Farm and 1984 fame, among others) stated in his treatise, Politics of the English language:

If it is possible to cut a word out, always cut it out.

Of course, that was OK for then. In the fast-moving agile world of today it should be written:

If it’s possible to cut a word, cut it.