Latest posts by techwriter (see all)
- 15 Questions to Ask After You Finish a Technical Document Project - February 12, 2018
- THY’s Perfect Information Design - February 9, 2018
- Waterfall vs. Agile Models in Technical Documentation - February 7, 2018
© 2009-2010 Ugur Akinci
Books are the bread and butter of technical writing and communication. Here are 10 ways in which you can improve the quality of the technical communication books you may end up writing during your career:
1) Always start from a clear outline that should become the basis for your Table of Contents. Make sure each main chapter is divided into easy-to-digest sections.
For example, a chapter on Auto Engine Maintenance can have sections on Carburetor Maintenance, Alternator Maintenance, etc.
2) It’s always a good idea to end your book with a detailed Index. Use nouns for your main entries and stay away from verbs. People usually do not search for “Editing” in an Index when they want to edit a Name. They first go to “Name” and then search for the sub-entry “Editing.”
3) The language and technical skill level of your book should be appropriate for the audience. It’s all right to have three jokes on every page plus a cartoon for every chapter if you’re writing a general-purpose “For Dummies” book. But it might be entirely inappropriate if you are writing for F-15 pilots or United Nations Committee Chairpersons.
4) Make sure everything you write is CORRECT. Design and format comes after that. In a technical book there is no excuse for incorrect facts and numbers, incorrect terminology, and incorrect tables, illustrations or call-outs.
5) Make sure everything you write is not only correct but also as SPECIFIC as possible.
When you write in a White Paper that “our chemical plants might be facing raw material bottlenecks within the foreseeable future,” this may very well be correct but it does not say much because it is not specific enough.
Compare the above with this: “our chemical plants in Freemont, CA and Clarendon, VA might be facing a 15% drop in the market availability of sulphur dioxide and magnesium chloride within the next 60 days.”
6) Make sure you have a Glossary that explains all acronyms, abbreviations and industry specific jargon used in the book.
7) Make sure your captions and headers contrast nicely with your body text. Serif fonts (like Times Roman) are easier to read in the body but sans-serif fonts (like Helvetica and Arial) stand out more for headlines and titles.
8] Make sure your graphics and images are relevant to your text and are placed right next to the text that they explain and illustrate.
9) When quoting Subject Matter Experts (SME), don’t forget to summarize their credentials for the credibility of your book. Instead of “B. B. Chandra said…” try “Dr. B. B. Chandra of the Indian Institute of Space Research said…”
10) And here is a last recommendation that I’ve seen neglected just too many times in technical books: always but ALWAYS put your book through a good spell checker before releasing it. A surprisingly good way to spell-check your documents is to skim through them BACKWARDS. It’s amazing how many misspelled words you can catch when you read something backwards. Try it and you might be pleasantly surprised.
For a better organized, more easily understood and compassionate world.