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 wondered if it was some new mind-controlling technique that would mean us writers would be out of a job. But, not to worry. It was useless for our profession and here is why:

  • Usability tests are 100 times better.
  • Readability tests are simply counting mechanisms. They count words, sentences, syllables etc.
  • Readability tests have no ‘intelligence’ behind them. They do not read text, they simply measure some parameters.
  • If a style guide is being followed and some form of simplified English is used in your organisation, a readability test will tell you nothing you do not know already.
  • Lastly, if you write for a discipline/profession where you must use specific terminology, the readability tests will score your content lower.

All in all, they feel a little silly to me. But – But – they are the type of programs that could develop into something special in years to come. Would that be our utopia or a thing from our worst nightmares?

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

Introductions to novels

V0040799 Oxen drive men, women serenade men and give them roses, a ho

This is not a technical writing topic, but about something I have thought for quite a while; why are introductions to novels at the beginning? Basically, are they introductions that you want to read at all. Do you not want to read this chapter after you have read the book.

Most introductions are for books that are part of a canon or are considered classics in some way. But, it is nice to have the novel fresh in your mind while you read the content of the introduction instead of reading it first. I dont know if this annoys much people, or if they have given it much thought, but I believe most introductions to novels are afterwords.

There, I’ve said it! Now, I can enjoy the weekend.



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

Serial comma (Oxford comma)



Commas seem to cause a lot of dismay among writers and subs generally. Their purpose, how they work, where to place them seems to cause unending consternation. I think that might be one reason there is some hostility to adding an extra comma before the conjunction to a series of three or more.

But, for technical writing, I believe it is imperative. There is no way around it; it removes all ambiguity to a list that is being described in a sentence. In technology and especially with a lot of new terms or terms that might not be overly familiar to a reader, it is very important that a clear distinction is made between every object in a series. This is why we, tech writers, like lists so much.

There are a lot of funny examples on why the serial comma is a good thing. Lynn Truss offers this up on it:

There are people who embrace the Oxford comma and people who don’t, and I’ll just say this: never get between these people when drink has been taken. Oh, the Oxford comma. Here in case you don’t know what it is yet, is the perennial example, as espoused by Harold Ross: “The flag is red, white, and blue.”

Lynn Truss goes on to say that she is ambiguous to it. Sometimes it’s a good thing and sometimes it doesn’t add anything is the gist of her opinion on it. But, in technical writing I think it should always be used. Why? 1) Because in a series it is the only way to completely avoid any confusion 2) If you have it as a rule, you are less likely to forget it. 3) Once you are in the habit of using it, it becomes second nature.

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

My plain English might not be your plain English

ScreenHunter_10 Jun. 17 17.04

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 and convoluted language in government literature especially.

But, in technical writing, there are words that we must consider are common everyday words to our audience that are not common words in everyday speech/literature. And this means we always need to be vigilant about the rules that we adapt to language use and its simplification.

For example, if you are writing some software documentation, should you spell out RAM? Do you need to? I don’t think so. But, if you were writing for an audience of librarians and you could not judge their level of computing knowledge, then maybe spelling out RAM would help them understand the concept.

The language is full of words, acronyms, and abbreviations that we don’t fully understand, but we still use them because we know we will be understood. For example, not many people nowadays know what ZIP – as in ZIP code – stands for. The answer: Zone Improvement Plan. Knowing this doesn’t help us enter our ZIP code though, does it?

So, instead of maybe adapting a rule in your style guide that states that all acronyms and abbreviations must be spelt out on first use, it could be better to state that it is worth considering if an abbreviation or acronym needs spelt out with reference to the target audience. And the same goes for specialist language – always refer back to the target audience instead of following a generic rule blindly.

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

Creating headers in Ditamaps

I found it difficult to find relevant information on the web about how to create anything below a level-heading 2. In my Ditamaps the heading 2 is the topic level and therefore, as soon as a topic is added to a map file, it becomes by default a heading 2. But I want to make a heading 3, how do I do that?

Here is an example of a Ditamap with headings 2 and 3:

<?xml version=”1.0″ encoding=”utf-8″?>
<!DOCTYPE map PUBLIC “-//OASIS//DTD DITA BookMap//EN” “map/dtd/map.dtd”>

<map id=”example” xmlns:ditaarch=”; rev=”1.0″>

<topicref href=”first.xml” >
<topicref href=”intro.xml”>
<topicref href=”description.xml” />
<topicref href=”dawn.xml”>
<topicref href=”dawn chorus.xml” />



In this example the topic called ‘dawn chorus’ is a heading 3. It is embedded under the topic ‘dawn’ by having the heading 3 before the end tag. Simple? Yes, and I hope I have explained it adequately.

Posted in DITA, Tech writer tips, 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 compact summation of the current thinking in technical writing circles.

I have no need to localize currently (and thankfully) and I appreciate the extra demands that localizing puts on documentation. But, I feel that Latin abbreviations should be used when they can.

Now, what I mean by that, is the most commonly used Latin abbreviations: i.e., e.g., etc. They are short and compact and for anyone learning English as a foreign language these abbreviations are seen as much a part of the language as anything else. They have entries in the dictionaries, their place in written English is very well established and therefore, they are easily recognized.

Why use ‘and so on’ or ‘and so forth’ instead of etc.? I think non-native speakers must find the alternatives to some Latin abbreviations much more confusing than the abbreviations themselves.

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?

For most writing and in speech there is no difference. But, if you are English (from England) and tend to veer towards using shall – be careful! In other parts of the world, most notably America, shall sounds pretentious and can convey negative connotations. I consider will as the better word to use in most documentation.

But, when documenting technical specifications shall is always used instead of will. This is because IEEE adapted its use as a standard and the definition of shall in this set of circumstances is:

Indicates requirements strictly to be followed in order to conform to a standard and from which no deviation is permitted.

And that is why both will and shall are used in technical documentation. I have a simple rule for using them: Will for all user documentation except specifications and shall for only specifications.

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