New Technical Writer Have No Fear Of Writing

New Technical Writer Have No Fear Of Writing



OVERVIEW

You're a​ non-writer who has just been assigned to​ write the​ User Documentation for your company's new product. Your overwhelming emotion is​ fear,​ perhaps with some anger.

With any new activity there will be some anxiety. Writing may have added anxiety because of​ your writing experience while you were a​ student.

Writing User Documentation is​ not like the​ writing that you had to​ do in​ school. Those activities were filled with anxiety and "writer's block." in​ this article you will see how to​ overcome your writing anxieties so you can write a​ good User Document.

WHAT YOU'RE NOT WRITING

All writing and writing situations are not the​ same. Let's differentiate writing a​ User Document from other types of​ writing and writing situations.

YOU'RE NOT WRITING a​ NOVEL

You don't have to​ worry about a​ plot,​ characters,​ and techniques to​ make the​ writing flow. You do not have to​ worry about transitions from one section to​ another; you don't have to​ worry about continuity. it​ is​ extremely rare for your Reader to​ read a​ User Document from start to​ finish; Readers usually only look up the​ information that they need at​ the​ time.

YOU'RE NOT ARGUING a​ POINT

You don't have to​ determine a​ point to​ argue,​ think up arguments to​ support that point,​ and then convincingly present the​ arguments.

YOU'RE NOT WRITING a​ LABORATORY REPORT

While lab reports provided a​ structure for writing,​ it​ was usually over-restrictive and those doing the​ grading were very picky regarding that format and structure.

YOUR SCHOOL-WRITING EXPERIENCES

At the​ end of​ your school writing exercise there was a​ critic (your teacher). Your goal was to​ impress him/her with your writing,​ all the​ time being extremely careful to​ write grammatically,​ and follow the​ prescribed structure. Later we​ will get a​ "critic" (editor) to​ be on​ your side in​ the​ writing project.

Writing a​ User Document is​ Different. the​ team is​ on​ your side. (I am ignoring office politics.) Everyone wants to​ have a​ successful product,​ and good User Documentation is​ part of​ a​ good product.

Remember that other members of​ the​ team are human,​ also. They have their tasks to​ complete,​ and would probably prefer not to​ have to​ answer your questions. Be prepared (read background info,​ etc) before you ask questions.

STRUCTURE MAKES WRITING EASIER

The overall structure of​ the​ User Document will follow the​ interaction between the​ User and the​ product. Within that structure you will write components...pieces of​ the​ User Document,​ each dealing with a​ specific topic. Each component will have a​ defined structure: overview/background,​ the​ actual material,​ and additional information.

One benefit of​ working this way is​ that you will not be concerned with "writer's block." the​ primary cause of​ writer's block is​ having making decisions ("what should I say here?"). an​ effective writing structure eliminates most decisions,​ and reduces your writing task to​ almost "fill in​ the​ blanks."

In fact,​ some experienced writers find it​ difficult to​ write in​ a​ modular environment. They are concerned with writing elegant transitions from one section to​ another. You do not need to​ do this...you can write each component totally independently of​ the​ others.

Your task is​ to​ clearly provide the​ information that your reader needs,​ and make that information easily accessible to​ him/her.

You must cultivate an​ attitude of​ compassion for your Readers.

YOU NEED RESOURCES FOR SUCCESS

Whoever assigned you the​ writing project (your "patron") is​ responsible for your success. Your patron should provide resources to​ assist you. One of​ the​ most important resources is​ an​ editor.

EDITOR

Your editor (if hired early in​ the​ project) can help you over many writing difficulties. For example,​ your editor can help you with wording problems as​ you write. Consult with your editor as​ you are creating the​ User Document...not just at​ the​ end.

Your editor is​ not your critic!

Your editor will reduce your worries about grammar and wording. Your editor is​ on​ your side; he/she is​ not an​ adversary or​ someone you have to​ impress (like your school teachers). Your editor can help you produce a​ good User Document.

ACCESS to​ INFORMATION

Your patron should enable you to​ have access to​ the​ product developers,​ information about the​ product (a mockup of​ the​ product,​ marketing information,​ assumptions about the​ Users of​ the​ product),​ and the​ industry.

TIME AND PHYSICAL RESOURCES

You need time to​ do a​ good job,​ and the​ physical resources to​ get it​ done.

If you are in​ a​ hurry,​ and if​ you do not know any of​ the​ current fancy authoring tools and content management systems,​ do not bother with learning them.

Instead,​ investigate what your word processor will do. Can it​ be made to​ create PDF,​ HTML,​ RTF or​ text files? if​ so,​ then it​ is​ a​ fine candidate for this project. Learn how to​ use its basic capabilities,​ especially its concept of​ formatting "styles."

TRAINING/GUIDANCE

Typically,​ documentation is​ started late in​ the​ project's life cycle. as​ a​ result,​ the​ documentation production is​ always rushed. Taking a​ live writing course may be out of​ the​ question: there will be scheduling problems,​ and you will be away from the​ writing task while you are being trained.

A better alternative might be to​ take a​ computer-based course that guides you through the​ writing,​ and supports you via e-mail. Visit the​ links in​ the​ "Resources" or​ "About the​ Author" section of​ this article.

YOU NEED a​ WRITING METHOD

To simply gather the​ required information,​ produce an​ outline that gets approved,​ and go off to​ write the​ document,​ is​ a​ recipe for high-stress and possible failure. It's high stress because at​ the​ end of​ your writing,​ you get everything evaluated at​ once. There is​ the​ fear of​ failure. Fundamental errors could result in​ a​ major re-write. Aaaargh!

Consider writing components (modules,​ pieces) of​ your document. Let a​ component sit for a​ while,​ review it,​ and then circulate it​ for review. This way you will know that you are on​ track early in​ the​ project.

Since components will usually be short and focused on​ a​ particular topic,​ your reviewers will actually have the​ time to​ read and comment on​ your components. Just providing a​ complete,​ massive document at​ the​ end of​ the​ project will discourage your reviewers from effectively evaluating the​ material.

Writing and having reviewed small chunks of​ text (as opposed to​ creating the​ entire document,​ and then having it​ reviewed) helps reduce your stress,​ enabling you to​ do a​ better job.

Recall a​ skill that you have learned. it​ may be driving a​ car,​ riding a​ bicycle,​ or​ solving differential equations. Remember how you got more comfortable as​ you worked at​ it. it​ is​ the​ same with writing your User Document in​ components. the​ first few components will be high-stress,​ since you are new to​ the​ process.

As you write and have your components reviewed,​ you will become comfortable with the​ process. the​ later writing will go faster and better because of​ the​ reduced stress. Your review team will know where you are in​ the​ writing process; they will see each component as​ you release it.

Contrast this with writing the​ entire document and then having it​ reviewed. Here the​ stress builds to​ a​ maximum at​ the​ hand-in and evaluation time. You never know -- until the​ end -- if​ you've made a​ fundamental mistake.

DEALING WITH REVIEWS of​ YOUR WRITING

You will have each component reviewed by others on​ the​ product project. Consider their suggestions and criticisms of​ your writing. However try to​ leave your ego out of​ the​ equation. if​ a​ reviewer says "you got this wrong,​" you should hear "this is​ incorrect." Ask what is​ incorrect,​ and get the​ correct information. Correct the​ inaccuracies. Don't be defensive.

If you can overcome your fear of​ criticism,​ you will be able to​ write more and write better. This fear will diminish as​ you produce (and have reviewed) each of​ the​ components.

Learn as​ much as​ you can about the​ product,​ its environment,​ and Users. if​ you are expected to​ be an​ expert and are not one,​ then use the​ excuse for any naive questions you may ask: "I am just simulating our product's Users with this question." (Use this technique sparingly.)

TWO MORE POINTS

Nobody writes the​ perfect User Document. Don't strive for perfection. Doing so will prevent you from getting anything done.

Read. Read all sorts of​ published materials,​ especially other User Documents (especially for products similar to​ the​ one you are writing about). Learn from that writing. Be critical of​ it​ from the​ USER's point of​ view.

FIRST THINGS to​ DO

Learn as​ much as​ you can about the​ product that you have to​ write about,​ its users,​ and the​ product's environment,​ before you ask questions (other than where to​ get information).

Visit the​ links in​ the​ "Resources" or​ "About the​ Author" section of​ this article. There you will find articles and resources to​ help you through this exciting task.




You Might Also Like:




No comments:

Powered by Blogger.