Hints & Tips

Helpful Tips To Improve Your Technical Writing Skills

Here are some hints and tips that can help you improve your technical writing and business writing and avoid costly and embarrassing mistakes.

All writing must be concise and to the point. Eliminate redundancy except when necessary for clarity.
All writing must follow a logical sequence so that the reader can clearly tell what steps to take in what order and what the results will be.
Do not use concepts before they are introduced.
Use transitions where appropriate. Make sure the reader does not have to hurdle unexpected jumps in thought.
Be consistent in the use of terms and abbreviations throughout the document or sets of documents.

Check hyphenated words or unusual usage in a dictionary.
Use only words that are common to the business community.
Be technically accurate and select words that accurately give a picture of what is happening. If you are unsure and it is important, find out the answer. Pay special attention to cause and effect relationships. Never use vague words to hide a relationship you are unsure of.
All business writing must be done in a timely manner—on schedule and on budget.

Be sure to provide small chunks of information to the reader. You don’t want the reader to have to scroll through page after page of information on screen. Break it up!
Check to see if the help screen works well in relation to the main program screen.
Make sure your hierarchical organization and branching is logical.

As you edit, keep in mind the document’s audience and purpose.

Read through the document initially to make sure the information flows, makes sense, and contains no glaring errors. Check:
- Clarity
- Consistency
- Up-to-date spelling and usage with national newspapers and Internet Mechanics (grammar, punctuation, and spelling)
Create a checklist of possible errors and read the document more critically.
Impose consistency on the document using a style guide.
Improve the organization of the document:
- Attach a template
- Use parallel construction for lists—consistent form and function
Break blocks of text into bite-sized pieces and use:
- Headings
- Bulleted/numbered lists
- Tables
Check word choices. Ensure the use of:
- Correct words
- Strong verbs
- Active voice
- Plain English—not jargon
- Consistent terminology when describing the same items or concepts
Tighten the writing.
- KISS
  - Short words (simple, direct)
  - Short sentences (20-30 words maximum)
  - Short paragraphs
- Eliminate obvious, needless, or redundant information
Correct the use of too many prepositions in one sentence.
Pay particular attention to transitions—add them if they are missing.
Use grammar/spelling checker, but do not rely on them—proof carefully.

Good Technical Writing is:

* Blake, G & Bly, R Elements of Technical Writing 1993

These hints will help eliminate unwanted surprises when reproducing reports and manuals. Today, much of the checking can be done on-screen. Make sure

All pages are there and are in the correct order
Pages have page numbers
There is a table of contents, acknowledgements, executive summary, or inside front cover
Page numbers in the table of contents. For tables that have been generated electronically, spot checking is usually sufficient
All headers and footers are accurate
Verify that the beginning of each chapter starts on the correct page

That all headings are consistent in style from chapter to chapter
Appendices follow the correct order and style
If the document will have two-sided pages, verify that the pagination is correct. In general, odd pages are on the right-hand side
If the document will have two-sided pages, some pages may be blank on the back side—typically in the front matter or at the end of a chapter. If a page is to be left blank, make sure you communicate this to your printer

And if time permits,

Check that all phone numbers, addresses, web addresses and cross-references are correct and that names are spelled correctly
Read the entire document, word-for-word. Check for misspellings, incorrect grammar, inconsistent terminology, and inconsistent capitalization

Copy can be improved with good subheads, captions, and closings. This article from The Business Marketing Association gives some helpful suggestions.

Writing Subheads

Subheads help break up the body copy into short, easy-to-read sections. And thoughtfully worded, informative subheads provide quick reference points for key information (descriptive subheads are preferable to too-short subheads). They also enable your reader to scan the page and come away with an outline of your message.
Subheads permit rapid communication with readers who have no time to waste. They also contribute a path for the eye. This can make your work look uncomplicated, and increased readership can result.
Write your subheads to tell a story by themselves, so you’re communicating even with the reader who only skims your copy.
As with headlines and captions, you can often extract subheads from the body copy you have already written.

Writing Captions

Exhaustive studies measuring readership show that many more people read the captions under illustrations than read the body copy. Using an illustration without a caption is wasting an important opportunity to enhance understanding.
Other research has shown that caption material (coupled with an illustration) is retained better even than a headline or an illustration alone!
Your caption should include a reference to your product or service and a benefit. The best captions are self-contained advertisements in themselves.
Of course, your illustration should be directly related to your message. As you can imagine, if your reader sees no connection between the illustration and your copy, their attention evaporates.

Writing Closings

Beware of weak closings! Just because this is the end of our business/industrial copy doesn’t mean the closing is unimportant—just the contrary. This is the last thing your reader will remember. And he or she may remember the entire piece as having the characteristics of the closing.
Try to leave your reader with one simple thought—preferably what to do next. If you want the reader to call your 800 number for more information, say so. But remember to give her a good reason to call. You may want to reiterate your main selling point, or repeat an example from your copy.
If you’ve made many points throughout your copy, you’ll want to summarize. But do this before the last paragraph, so you can hold to one point in your closing.

Click on the following links to view other helpful web sites.

Purdue University Online Writing Lab:
http://www.owl.english.purdue.edu

The University of Illinois at Chicago Online Writing Lab:
http://www.uic.edu/depts/engl/writing

The Kent State University Online Writing Lab:
http://dept.kent.edu/English/eslowl/