Latest posts by techwriter (see all)
- Test Your Knowledge of 4 Basic Fonts – Drag & Drop - January 27, 2017
- How NOT to Design a Web Site - January 25, 2017
- Hazards of Poorly Written Technical Documentation - December 26, 2016
© 2010 Ugur Akinci
It’s best to have a colleague or an outside reviewer to read and edit your technical documents. But sometimes you might now have that luxury and you may be all alone.
So how should you edit your own stuff?
I can only give you a few tips that worked for me in the past.
(1) First off — the OBVIOUS — put your document through a Spell Checker. You’d be amazed how many writers forget to do that. That will certainly catch the roughest mistakes.
But that’s not enough. For example, the spell checker won’t catch “right” misspelled as “might” since both words are spelled correctly but only the former is correct semantically.
(2) Check your links. In FrameMaker this is so easy. You make a search for “Unresolved Cross-Reference”. Period.
(3) Read all your figure CAPTIONS and table TITLES. Make sure they are correct.
(4) Check your procedural steps and make sure they all start with an ACTION VERB. A description should not be a numbered step in a procedure.
(5) Make sure every acronym is written in open form at least once, preferably, the first time you use it.
(6) Make sure your conjunctives (and, or, etc.) are necessary. That’s a habit carried over from the way we usually speak, by inserting all kinds of “and”s and “like”s, etc. in between our independent clauses. If not, they’ll lead to unnecessarily complex compound sentences.
For example, take this sentence: “The dial show 200 volts and that’s something you should report to your manager.”
You can re-write it as two separate sentences: “The dial show 200 volts. You should report that to your manager.”
Or again a single sentence, written as a conditional (IF) sentence: “If the dial show 200 volts, report that to your manager.”
(7) Scan your whole text from REVERSE! Yes, I’m not joking. It’s amazing the things you can catch when you flip through a document by starting at the last page and going backwards to the very first page. That circumvents the mind’s built-in structuring reflex and thus helps you see spelling errors much more quickly. It works.