Tag Archives: good writing

Readability tests

I once had a colleague/SME asking me if I used readability tests for checking the technical documentation. “Something like Flesch-Kincaid” he said. I had no idea what he was talking about. It sounded sinister with the name ‘Flesch-Kincaid’ and I … Continue reading

Posted in Future of tech writing, Tools, Usability studies | Tagged , , , , , , , , , , , | Leave a comment

My plain English might not be your plain English

There are a lot of words that are known to only specialists and can make non-specialists feel like outsiders. The Plain English Campaign in the UK and its sister organisations in other countries tries to confront the problem of specialist … Continue reading

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

Latin abbreviations in technical writing

Many style guides as well as simplified English and plain English campaigners share a common goal of wanting to eradicate Latin loan-words from English, and this includes Latin abbreviations. This post from a 2012 entry on ferswriteshoe blog is nice … Continue reading

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

Shall vs. Will

In an earlier post, one in which I was trying to be funny, I mentioned shall or indeed, shalt, as a sign that god was a technical writer. But, when do you use shall or will? What is the difference? … Continue reading

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

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 … Continue reading

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 … Continue reading

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 … Continue reading

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

Killing interest in your documentation and how to fix it

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 … Continue reading

Posted in Style Guide, Usability studies | 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 … Continue reading

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

God is a technical writer

The ten commandments is possibly the most famous piece of technical writing in the western world and it was written by God himself (or so you might believe if you are a member of one of the Judeo-Christian religions). The … Continue reading

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