Tag Archives: editing

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

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

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

Passive voice in tech writing

Use the active voice and never use the passive voice, ever! Does this sound familiar to tech writers? It is written into style guides, it is in Strunk and White (and Geoffrey K. Pullum does a nice critique of it that I … Continue reading

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

Strunk and White review by Geoffrey K. Pullum

A brillaint review of Strunk and White can be found here. Called 50 Years of Stupid Grammar Advice the author, Geoffrey K. Pullum, pulls no punches. He dissects Elements of Style and shows its many wayward and plainly wrong advice. It also … Continue reading

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

Editing: read aloud

When editing and reviewing your own content or someone else’s, there is one tip I can give which I think surpasses all others: read aloud! Spoken word is much older than the written word and it is the rhythms of … Continue reading

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

Some words and phrases to consider avoiding in tech writing

Moot point – avoid at all costs. Audience may not know what moot means. To be honest I have never seen this in tech writing, but have seen it a lot in journalistic writing. Nevertheless – There is nothing wrong … Continue reading

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