INKWELL NEWSWATCH 
Monthly Online eZine  
News And Views For Working Writers

INdex 
 
 INside Scoop
 
 ON THE COVER
 
 INside AUTHORS
 
 COLUMNS
 IN Her Own Write
 INscribe
 Pen IN Hand
 Write On!
 INstruction
 
 WRITER'S LIFE
 Fiction
 Nonfiction
 Screen & Stage
 Poetry
 
 TOOL KIT
 Top 10 Resources
 Advice/Q&A
 Features
 Book Reviews
 Items Of INterest
 Global Offerings
 INside Services
 
 INside CHUCKLES
 Bill The Bard
 The Writer At Work
 Games & Puzzles
 
 FREEdom STUFF
 Classifieds
 Syndication
 Classic eTexts
 Free Software
 IN Banners
 
 ABOUT IN
 Who's IN
 What's IN
 Submissions
 Editorial Calendar
 Advertising
 Join IN's Team
 Contacting IN

IN Front Cover




Search

Learn To Be A Better Journalist

Buy Classic Literature Collections

Acclaimed Screenplay Writing Software

Books On How To Write Fiction

Become A Well Paid Travel Writer



Vote daily and raise our ranking!


TOOL KIT
Items Of INterest
January, 2008


Flying by the Seat of My Pants

Part I: What Is Technical Writing?
Another world of opportunity
By  Patrick M. Kennedy

Express your love for technology with a little technical writing.
Writers are now and then called upon to create technical documentation. The majority of us can do it, for sure, but for those unsure there are certain guidelines that lead to success. Effective pre-planning and keeping it concise are two of the keys to successful technical writing. Here, we provide an overview that will scratch the surface of the field.

Some of the elements to be considered include:

  • Knowing the audience
  • Understanding the final product or medium
  • Setting the attitude and approach
  • Writing style, choice of words, and clarity
  • Knowing the purpose of the document and the level technical detail required

Begin by defining the audience or end users. Are they professionals who will be fundamentally familiar with the subject of the document? Is the reader an engineer, a manager, a technician, a student, or a high-end user? Will the document be used for training, programming, marketing, or for general information only? This is a factor that must be determined before the writing begins to settle on the technical depth, word choices, and attitude of the writing. It is also necessary so information is not written down to the professional, or over the head of the layperson.
 
Become familiar with the final products of technical writing, such as user guides, software manuals, hardware manuals, maintenance and repair manuals, testing guides, training material, standard operating procedures, and many others. As a technical writer, you may be asked to write web content, computer-based training, online help systems, or marketing material. Each of these final products has its own conventions and limitations the writer must be aware of before starting the assignment.

A good way to become familiar with the different types of technical documentation is to browse some of the high-tech websites of well-known companies. Look for the areas of the websites that contain support information. Notice that you can read the content in HTML and often download it as a PDF file.
 
Standard documentation is the most common final product and involves writing detail and explanation, including graphics and references. This usually includes complicated detail and the most important focus for the writer is to keep the detail well organized. Keeping the common chunks of information grouped together and in the proper order keeps the reader involved and better informed.
 
Web content must be brief, direct, and to the point with a minimum of words because it is viewed in a limited screen area. Much like advertising copy, the web page must sell itself at the first glance or the readers will jump to the next page at the click of a mouse.
 
Online help systems are a combination of the web page and the standard documentation copy. There is normally a great deal of detail, but it must be in brief and focused chunks. Each statement or paragraph must stand on its own because the normal process of moving from link to link in a Help File will force detachment from the previous paragraph; thus, it must speak for itself.
 
Marketing material for high-tech products must be a combination of all of the above with the over-riding aura of a sales pitch tying it all together. Photos and graphics are often a part of marketing materials. Write the copy so it stands on its own. Do not describe the colors because they are in the photo; do not go over the numbers because they are in the graph; but explain why the colors and numbers should be on the reader’s desk or in their business.
 
When starting a new assignment, most writers are baffled by the definitions, word usage, and acronyms used by the developers or engineers. Compiling a list of definitions and acronyms for personal understanding is a good start, and more than likely, you will use the list when you create documentation.
 
As a technical writer, you are the reader's advocate. The quicker the reader comprehends the documentation, the more effective it is. Write specific rather than general information. Technical readers are usually interested in details such as facts, figures, conclusions, recommendations, and especially how to use the technology to achieve a specific outcome. The key here is to make it clear and to the point. Keep a tight focus.
 
Write in a clear style, keeping it simple and direct, expressing the point in a relaxed and professional manner. Avoid the passive voice like the plague. Action must be expressed directly rather than indirectly.

So there you have a broad overview. We'll have a look at some more of the elements particular to technical writing in the next edition of IN. 'Til then, take some time to become familiar with the various types of technical documentation. Your computer, printer, and cell phone all came with some sort of manual or user guide. See if you can identify the ideas here exemplified within that documentation.

IN Icon



Patrick M. Kennedy has been a professional writer/editor/graphic artist for 30 years. He has published a novel, short stories and poems, articles in magazines, and he contributes a regular lighthearted column to the Senior Wire News Service. Find more about his background, writing samples, and services at: www.abetterword.com 


Sign Up and Use Our New Forums! Voice Your Opinion! Discuss Our Content! Ask for Writing Assistance. Post Your Successes, Queries or Information Requests. Collaborate with Other Writers.

© Freelance Writing Organization - International 1999-2049

Items Of INterest
IN This Issue
Constant Improvement
We're Getting Older! Thank you!
Standing On The Digital Platform
NaNoWriMo Wrap
Official Words From Pop Culture
NaNoWriMo Killed Her
Career Fair For Women
Unotchit LongPen™
Norman Mailer: American Literary Giant
Writer, Inventor, I Am

Support IN
Receive Free Gifts
$20.00 Voluntary Contribution
$35.00 Voluntary Contribution
$50.00 Voluntary Contribution

New Novelist Software


Effectively Manage Your List


Writers Digest 101 Site Award






Your Ad Here

Traffic Swarm For Writers


Hottest Books This Month!

Whose Books Are Turning Into Movies?
Bald Ego
Mouse Over To Pause

Writer’s Block
The path to inspiration starts
Upon the trails we’ve known;
Each writer’s block is not a rock,
But just a stepping stone.

Poetry Is Not
Penned to the page
Waiting for us to admire.
It is only a lonely thought
Caught by tears on fire.

Silent Echoes
A quiet rhyme upon a page
Is what a poet gives;
Some gentle words whispered in trust
To see if memory lives.

Bard From Deadlines
What makes a poem finally work
Is not the time it takes;
It’s how the poet used the muse
To prophet from mistakes.

Be Mused
The art and craft of poetry
Are not so far apart;
The craft comes from the cunning,
The rest comes from the heart.

Fine Vintage
Don’t plant your poem on the page
As though you’re hanging drapes;
It’s shape and flow should come and grow
Like wild summer grapes.

Getting It Write
Writers write what they know best,
Their passions, fears, and dreams;
Writers rarely write about
What other call their “themes.”

Double Vision
A writer’s life is paradox,
It’s more than what it seems;
We write of our reality,
The one inside our dreams.

Poetry
The echo of a promise,
The thunder of a sigh,
The music of a memory,
A child asking why.

Letter Perfect
Twenty six symbols arranged on a page
Can send a soul to heaven or torment it with rage,
Can free a fragile world or hold it in its net--
The power and the magic of the mighty alphabet.

The Write of Passage
The jump from writing just for fun
To getting paid for it
Begins when you first realize
You know you’ll never quit.

Pegasus
It is not the magic of his wings
That sets us free from our bond.
It is the muse within ourselves
That lets our words lift us beyond.

Photo Poet
Consider your mind the darkroom,
Consider your life the lens,
Consider your eye the camera
On whose focus the poem depends.

Rising Moon
A poem is a rising moon
Shining on the sea,
An afterglow of all we know,
Of all we hope to be.

Star Light
Writing a poem,
Reaching a star,
In making good art
We find who we are.

Spider Web
A poem is a spider web
Spun with words of wonder,
Woven lace held in place
By whispers made of thunder.

Re-Verse
The final draft upon the screen,
At last my poem’s through;
A verse of only four short lines--
I rewrote twenty-two!

Read All Of Charles Ghigna's Poetry at FatherGoose.com


Our Own Banner Rotator System
Any banner seen below is either our own or one of our members.
Support the cause - click a banner.


Want Your 468x60 Banner Above? It's FREE For Newly Published Books

© Freelance Writing Organization - International 1999-2049
All Rights Reserved. Copying in any way strictly forbidden.
Our Disclaimer Is Based Upon McIntyre's First Law: "Under the right circumstances, anything I tell you may be wrong."