To write a technical article, one just surely needs technical knowledge. Well, no. The very best technical writers take enormous pains to present information in an interesting way. This isn’t a mysterious art at all, and the technique can be learned just as easily as square-dancing. Journalists are taught the technique though they often forget. We give just a few pointers.
Why, one wonders, should technical writing be so boring to read? The writers within the IT industry almost try to make a virtue of their ability to repel the readers.
Part of the problem is that there is no best-practice to emulate. We have a lot to be ashamed of in the way we communicate. Another aspect of the problem is that a lot of writing is not even intended to convey meaning; instead, it is a technique for obfuscating technologies, in embellishing the importance of the writer, or in conveying the vague impression that a particular technology is splendid.
Writers like to suggest that they possess a mysterious art. In truth, it is not a matter of talent, but craft. Nobody is born with the gift of welding, busking or programming: all crafts are learned through graft, sweat, and self-criticism.
Capture the readers’ interest as soon as possible
The commonest mistake is to write a dull first paragraph. Most readers will not tolerate such a thing. Even in technical writing there is no excuse for that.
Any aspiring author who is writing in English need do no more than read the first paragraph of the novel ‘Moby Dick’, by Herman Melville, to see the perfect way of starting.
‘Call me Ishmael. Some years ago- never mind how long precisely- having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world. It is a way I have of driving off the spleen and regulating the circulation. Whenever I find myself growing grim about the mouth; whenever it is a damp, drizzly November in my soul; whenever I find myself involuntarily pausing before coffin warehouses, and bringing up the rear of every funeral I meet; and especially whenever my hypos get such an upper hand of me, that it requires a strong moral principle to prevent me from deliberately stepping into the street, and methodically knocking people’s hats off- then, I account it high time to get to sea as soon as I can. This is my substitute for pistol and ball. With a philosophical flourish Cato throws himself upon his sword; I quietly take to the ship. There is nothing surprising in this. If they but knew it, almost all men in their degree, some time or other, cherish very nearly the same feelings towards the ocean with me.’
See? Did you notice the hammer-blow of the sentence that starts ‘Whenever I find myself going grim about the mouth….’, after the simple first sentence? The way it reads as if he was really speaking directly to you? Did you notice the ingenious rhythms of the sentences wrought through the clever mix of syllables? No? It’s only because you aren’t analyzing why some communication works, and why others don’t. It wasn’t just talent by Herman Melville, it was as calculated as putting up a pair of shelves.
Ah, you say, that’s a novel, easy, what about a text book? No problem, Read this. It’s the start of ‘The Age of Scandal’ by TH White.
Well, we have lived to see the end of civilisation in England. I was once a gentleman myself. When I was an undergraduate at Cambridge, the Master of a college was a fabulous being, who lived in a Lodge of breath-taking beauty and incalculable antiquity, tended by housemaids, footmen and a butler. There he consumed vintage port, wrote abstruse treatises if the spirit moved him, and lived the life of an impressive, cultivated gentleman. Such posts were among the few and noble rewards rightly offered to scholarship by the civilisation which then existed.
When I last stayed in Cambridge, I lunched with two Masters of colleges. Both of them had to help with the washing-up after luncheon.
There was a comic story current shortly after the Hitler war— one tried to think that it was comic. It said that there was some conference or other at Lambeth, thronged with archbishops, cardinals, patriarchs, moderators and so forth. The Archbishops of Canterbury and York were seen to be in earnest consultation in one corner of the room. Were they discussing a reunion with Rome or a revision of the Prayer Book? Thrilled with the ecclesiastical possibilities of such a meeting, one of the stripling curates managed to edge himself within earshot of these Princes of the Church. They were discussing whether it was worse to wash-up or to dry-up.
A poker-faced, TH White, in mischievous mood, starts with a shock, and then uses his facile virtuosity to attempt to justify the impossible. He then does an elegant pirouette into the comic. The reader is jolted into attention. This is going to be no ordinary History book.
So what is the message from these examples? The masters of literature use spoken language, There is no separate convention for written prose. They hit you with fresh ideas and subvert your prejudices to get your interest. They jolt you into attention. Don’t worry, if you can’t be brilliant, then be clear and simple so that your readers will be grateful, and continue to read.
Keep things brief
Think, for a moment, of those things that you’ve read that have made the most impact on you. Short, eh? A good writer will rework material constantly to refine it and presume less on the patience of the reader. There is a well-known adage in the IT industry that the average manager can read just one side of A4 before his attention wanders. I’m surprised, from my own experience, that it is that much.
Work to a strict framework but then remove it
When a house is built, then the scaffolding is removed. Often, in technical writing or academic work, not only the scaffolding is left, just to prove that the house was properly built, but the cement mixer is left in the garden. Essays are littered with headings like Introduction, Summary or Conclusion. Ironically, they often aren’t.
All writers need structure. I once called in to see Duncan Kyle, the novelist. His study wall was a sea of notes, pictures, and references pinned everywhere as he worked on his next action thriller. Months of work preceded the typing of the first draft. PG Wodehouse famously pinned his stories around the wall of his study at a height commensurate with the quality of the page. He worked at them until they all reached the ceiling.
I like to use the old schoolmasters’ trick, where you start by filling in a grid marked ‘What?’, ‘ Why?’, ‘Who?’, ‘Where?’, ‘When?’, ‘How?’, and then sequencing the various ways that you answer those questions, and developing the structure from these ‘nuggets’.
Notice that scaffolding conforms exactly to the shape of the house. You should never use a standard shape or put the scaffolding up before you’ve designed the house.
Periphrastic perambulations are anathema
Keep words short where possible, but pop in the occasional polysyllable just to help the rhythm of the words. With technical writing, you must never use abbreviations without defining them, even if they are well-known in your immediate circle. When using a highly technical sentence, a useful trick is to follow it with the same message written in simple English. That gathers up all your readers, whatever their prior knowledge, to lead them onwards. Be sympathetic with all those keen and interested readers who are not native English speakers. They will not thank you for show-off words as in the heading of this section.
It is said that the effect of eating too much lettuce is `soporific.’ I have never felt sleepy after eating lettuces; but then I am not a rabbit. They certainly had a very soporific effect upon the Flopsy Bunnies!
Beatrix Potter, at her majestic peak, gives the perfect example in her ‘Tale of the Flopsy Bunnies’. How poorly it would have read without the word ‘Soporific’.
In the fourteenth century, John Wycliffe made the first English translation of the bible in the spoken Yorkshire dialect of the common man. Its effect on English literature was far more profound than that of Shakespeare. If you can convey complex messages that simply, why feel the necessity to make anything more complex?
In the bigynnyng was the word, and the word was at God, and God was the word. This was in the bigynnyng at God. Alle thingis weren maad bi hym, and withouten hym was maad no thing, that thing that was maad. In hym was lijf, and the lijf was the liyt of men; and the liyt schyneth in derknessis,and derknessis comprehendiden not it.
Convey the emotion
When writing in the academic style, we are trained to write like a disembodied entity, devoid of all emotion. This is why academic essays are never read for pleasure. All literature, comic or tragic, is about the clash of emotion. To write well about technical subjects, one has to be interested in the subject and aware of the human struggles and mistakes behind any technology. The effect is subtle but profound. If your heart isn’t in it, you should never go near the keyboard.
Here is LTC Rolt, the engineering historian, with a classic paragraph from his book ‘Red for Danger’ on the history of accidents on Britain’s railways.
One of the most tiresome and menacing of the early experimentalists (in the early railways) was Doctor Dionysius Lardner, a character strongly reminiscent of ‘Beachcomber’s’ Doctor Strabismus. That he enjoyed for a time a great reputation as a railway expert was due to the fact that he was one of the first masters of the art of blinding the layman with science, but that he was able to impose upon the railway companies themselves is more mysterious. Speaking against Brunel’s proposal to construct the Box Tunnel on the main line of the Great Western Railway with a continuous gradient of 1 in 100, the Doctor pronounced that if the brakes of a descending train were to fail as it entered the tunnel it would emerge at a speed of 120 miles per hour, a velocity at which no passenger could breathe. Brunel pointed out that the Doctor had failed to take into account either frictional or wind resistance and that the speed would in fact be only fifty-six miles per hour. But the savant’s self-esteem remained unshaken. With an inconsistency surprising in view of this first gaffe, we next find him pontificating against the broad gauge on the grounds of the increased ‘atmospheric resistance’ of the wider vehicles. It is obvious that a man of the calibre of Isambard Brunel knew perfectly well that Doctor Dionysius Lardner was a pompous fraud and yet for some extraordinary reason the Great Western Company gave him the use of an experimental train and the liberty of their tracks. For the two months of September and October 1838 the Doctor’s train was at large on the main line to the extreme hazard of the regular services. It was asking for trouble and, sure enough, it came. On September 26th George Henry Gibbs, promoter and director of the Company wrote in his diary: ‘the eight o’clock train ran into the experimental train and injured three of the carriages very much’. Did the Doctor apologize? Did the Company order him off? Not a bit of it. He seems to have assumed the rights of royalty and wrote the Great Western board a furious letter which Gibbs described as ‘Very improper’. A month later the experimental train was again involved in a collision. Fortunately, or perhaps unfortunately from the Company’s point of view, the sage was not on board on this occasion and it was his unfortunate pupil who paid the penalty. He was killed on the spot.
Cite and acknowledge sources
The technical writer must behave with exaggerated courtesy. For some reason, humanity strains to give a compliment, and to acknowledge good work in others. Criticism seems more natural. The author should cite all quotations and sources of any information as he would in an academic treatise. Not only do the authors appreciate it, but the writer of the article shows that at least he has done his homework. Any article used or even glanced at in the preparation of some writing should be listed at the end of an article as a source. it costs nothing to thank anyone who helped with the article as well.