Book review part two: For Who The Bell Tolls by David Marsh


I wrote about this book in an earlier review. Well, I just want to add that the second part of Chapter 6 has become invaluable to me. It starts under the sub-heading More Words That Cause Confusion, Anger or Despair. This section taught me how much I still need to learn about words and how to use them.

The section is done alphabetically and goes through words that are confused, misunderstood or just quite often used wrongly. Here is an extract:

derisive or derisory?

The former means contemptous, as in a yell of derision; the latter means unworthy of serious discussion, as in a derisory offer.

This was very enlightening for me, I always get this mixed up. And, I could go on and on with quotes from this section. My eyes were indeed opened wide with shock at my own ignorance and at the amount of words that can be mixed up.

This section has become one of my most precious reference material now and if I am confused about a word it is one of the first places I will peruse for recourse.

It is also very useful if you use both British English and American English, as it describes some of the words that are can be confused with either spelling or meaning between the two forms.

Posted in Books | Tagged , , , , , , , | Leave a comment

Hiring a tech writer: cross-over skills


Hiring someone with the right skills for a position of technical writer can be difficult. The job is more diverse these days and cannot be merely pigeon-holed as ‘manual-writer’. In fact, the skills and expertise needed between one tech writer position and another can be poles apart. For example, if you are working on hardware documentation and have only ever worked on hardware documentation would you be right for a job in a software company?

Anyway, with all that aside, there is another issue when you have advertised a technical writer position. You may receive lots of applicants who have never worked as a technical writer before but who have experience in other fields that may be closely related. What do you do? How do you deal with these type of applicants?

If you are looking for a senior technical writer, then you need to find someone with previous experience as a technical writer. It will not work trying to find someone from another profession.

However, for an entry level job or if you are looking for a junior technical writer (someone with a couple of years experience), then I think you can also look at applicants who are coming from non-tech writing backgrounds but who have cross-over skills.

So, what type of backgrounds could this be. Well, here is a list of the backgrounds that have some cross-over skills with technical writing:

  • Marketing: writing skills, awareness of audience, usability, information design.
  • Technical support: awareness of audience, writing skills usually, customer-focused, usually technically savvy.
  • Teaching: aware of instructional approach to learning. (I do not rank teacher’s cross-over skills very highly because the emphasis tends to be additionally on their language and grammar skills. Unfortunately, teachers can be tied to out-dated forms and be a little conservative when it comes to language use.)
  • Graphic designer: graphical layout, usability, customer-focused.
  • Copywriter: writing skills, awareness of audience.

There is, I am sure, more professions than this that have cross-over skills with tech writing. But, I think the main skills that you are looking for from someone who has not worked as a tech writer before are: writing ability, technical ability/aptitude, user awareness, information design.

And how, apart from a CV, can you find out if they have these abilities? Set them a test.

Posted in Hiring a tech writer | Tagged , , , , , , , , , | Leave a comment

Thomas Pynchon: tech writer and fictional writer


As a technical writer it is refreshing to see that the experiences you have in the profession can be made into works of art. Case in point: V. and The Crying of Lot 49 by Thomas Pynchon. Interestingly, the only other writer (I know of) who began as a tech writer also went to the same university and was in the armed forces, namely Kurt Vonnegut.

There is ample evidence in Thomas Pynchon’s writings of the influence of his experience as a tech writer. It is there in the names, in the weirdly matter of fact, blocky sentences that still somehow contain a lively aesthetic. It seems to run through his works as one of the foundation stones.

For a really nicely lucid piece of his prose on a technical subject, you should read this: Togetherness . Look at how he uses the styles of tech writing that are still in use today. But, they are not a hindrance to his own style, instead they compliment it by adding a weighty element of technicality that coincides brilliantly with the content of the prose.

I have not read much of his work, but I plan on changing that in the next few weeks and months.

Posted in Books | Tagged , , , , , , , , , | Leave a comment

Machiavelli for tech writers



Tina the tech writer could have done with a bit less passive aggression and a bit more canniness. The muttering, grumbling tech writer who is forever being overruled touches a chord with a lot of people in our profession. So, what can be done for a tech writer to gain more influence within an organization?

Here is my (and I hope its not too Machiavellian) suggestions for steering documentation concerns:

  • Don’t complain to fellow tech writers or other colleagues about how powerless you feel. The more you complain about it, the more you enforce it.
  • Write a list of issues that you see as impeding documentation projects.
  • Take the list up with people that you think can do something about it and help you change things to your (and documentation’s) advantage, i.e. a manager, for example.
  • Never be afraid to let others know your opinion, but do it in the right forum, i.e. meetings, not at the coffee dock.
  • Push ideas forward in a positive way and never dwell on how bad things are now; look for solutions.
  • Make lines in the sand between tech writer’s sphere of influence and others in the organization by formalizing processes and input as much as possible. It is all too common that engineers stick their noses into your business.
  • Emphasize your (tech writer’s) skills and importance to the organization (but again, more important to do this with those with power in the organization and not all and sundry, otherwise you will be exhausted from talking).
Posted in Tech writer tips | Tagged , , , , , , , , , , | Leave a comment

Killing interest in your documentation and how to fix it

killiney hill

Imagine you are sitting on a train and looking out the window. The landscape you are passing through is flat and brown; fields at the bordering time of year between winter and spring. One field looks like another, with electrical pylons running through them that instead of breaking the monotony just seems to add to it. You turn your gaze away from the window and start dozing off.

When you wake up the landscape the train is passing through has changed; undulating hills, with patches of deciduous forest and mountains cutting the horizon. You sit up and take notice, drinking in the landscape – you want to keep looking – because it keeps on changing and you are drawn to it.

Now, think of how you write your technical documentation. If every single sentence you write is of the same length and same rhythm, you are doing yourself a big disservice. The poor reader is probably dying of boredom and just wants a snooze. All you are doing is sketching out big brown fields.

Like undulating hills, you need to infuse your writing with rhythm that changes the tempo now and then, thus making it interesting. Its not that hard, but is not often done in tech writing.

Here is a tip to get started, try and write a paragraph of technical documentation with sentence lengths that correspond with this sequence:

Long, short, long, short, short, long.

There is no reason you cannot do this even with the most mundane pieces of text. And once you do it will transform your reader’s experience and make it a little more enjoyable.

Posted in Style Guide, Usability studies | Tagged , , , , , , , , , , , , , | Leave a comment

The long and short of it: Conciseness and quickness in writing


One of the greatest Italian writers of any century, Italo Calvino, was supposed to deliver a set of lectures in Harvard in 1985-86 but tragically died just beforehand. However, the drafts of the lectures he was going to give have been published in essay form and are a treasure trove of ideas and theories for any writer (in any discipline).

Here is a little extract on conciseness from that collection of his essays:

In the even more congested times that await us, literature must aim at the maximum concentration of poetry and of thought…I would like to edit a collection of tales consisting of one sentence only, or even a single line. But so far I haven’t found any to match the one by the Guatemalan writer Augusto Monterroso: “Cuando despereto, el dinosauro todavia estaba alli” (When he woke up, the dinosaur was still there).

It seems to me that Calvino predicts flash fiction, twitter, text messaging, and the rise of the novella in that one estimable sentence that begins “In the even more congested times…”

Not only has the population of the world dramatically increased in the last century, but now a large chunk of that population can begin communicating with each other. What congestion! The congestion can certainly be felt when you are hacking through the verbiage online to get to some golden nugget of information.

But the good news is that it seems that with the huge possibilities there are for storing vast amounts of information that instead of writing getting more long-winded it is in fact shortening. Brevity in a congested life is a big advantage. People don’t have the time to read huge tomes anymore for work or pleasure and there has been an explosion in bite-sized chunks of wholly formed stories etc. that seem to be fast taking precedence.

There is a risk attached to this, however. With conciseness comes the possibility of making something too cryptic; opening content to multiple interpretations. But, this can also lead to the joy of more imaginings.

Posted in Books | Tagged , , , , , , , , , , , , , | Leave a comment

You don’t read with your head but with your heart


As it is just after Valentine’s Day, I thought this would be an apt subject to write about. Technical writing is one of the most conservative corners of the documentation/writing world. We pull faces when we see a new unapproved word being used in our documents and we pull even bigger faces if we see too many italicizations or other means to highlight text.

And yet…and yet…when we read text, any text, we read it with an emotional response. We like to be put at ease when we read (that’s why we have introductions) and we like to feel the writer cares about us. And one way for a writer to show they care about a reader is by highlighting those things that he/she deems important. One way of doing this is by using italics, bold, and other forms of emphasis.

The emotional response of a reader is something I don’t often think about. Yes, I look at documentation with the keen eye of someone with knowledge of usability, but I never really think of the emotional  response of the reader. There is a subtle difference. When thinking of an emotional response, there is more of a sense of pulling the readers sympathies in a certain way. Also emotional elements in documentation exist in the micro-climate of sentences instead of the macro-climate of paragraphs etc. where usability lives.

So, I will try and be more emotional in my tech writing from now on (or at least look at sentences from this angle).

Posted in Usability studies | Tagged , , , , , , , , , , , , , | Leave a comment