Great Technical Writing Beware Of Your Editor Love Your Editor

Great Technical Writing Beware Of Your Editor Love Your Editor



Overview

Your editor should be an​ integral part of​ your writing team. Do not think of​ him/her as​ a​ judge,​ but rather as​ a​ resource to​ help you in​ all phases of​ the​ writing project. This article will help you overcome any fear of​ your editor,​ and how to​ effectively use your editor during the​ writing process.

Beware of​ Your Editor

Some of​ the​ changes that an​ editor might suggest could make the​ User Document more difficult for your Reader to​ understand.

Improving Your Writing

Once your editor has gotten past the​ basic mechanical editing tasks of:

* grammar

* punctuation

* spelling

* editing to​ a​ Style Sheet,​

he/she may work on​ "improving your writing."

Your editor may believe that one way to​ make the​ writing more interesting is​ to​ use synonyms when you refer back to​ something. Thus you might call something a​ "chip bin" in​ one part of​ your text,​ and your editor might suggest using a​ different term,​ such as​ "waste trap,​" later in​ the​ document. This should make your writing "more interesting."

You do not want interesting writing in​ your User Documents! You want clear,​ simple,​ very easy to​ understand writing. if​ you make your writing more interesting by using the​ synonym ("waste trap") then you force your reader to​ have to​ think about whether or​ not these are the​ same thing. I recommend that you use the​ exact same wording every place in​ your User Document where you are referring to​ the​ same thing. No synonyms here!

If your Reader wanted to​ be entertained or​ have his/her thoughts provoked,​ then he/she would be reading a​ novel.

Don't let your editor make your writing more interesting or​ more clever if​ those efforts makes the​ material harder for your Reader to​ understand.

Erudition

Another place to​ beware of​ your editor is​ "erudition." That is,​ when an​ editor that tries to​ make your User Documentation sound more formal. Other than disclaimer,​ legal,​ and safety information,​ the​ User Document should sound friendly,​ with a​ conversational tone.

For example,​ an​ editor might suggest changing contractions (such as​ "don't") into their more formal form ("do not"). Don't do it! Contractions are conversational and they should not be avoided.

If you think about it,​ most people reading the​ User Documentation for any product are under some form of​ stress:

* they either want to​ get on​ with using the​ product,​ or

* something has gone wrong.

A formal document will put the​ User off. the​ document should not be silly or​ flippant; however,​ it​ should provide the​ information that the​ User needs in​ a​ conversational,​ easily understood style. the​ needed information should be easy to​ find.

Although most word processor grammar checkers are woefully inadequate,​ many of​ these checkers can be made to​ provide a​ readability score (you may have to​ set an​ option to​ enable this feature). Editing should help increase the​ readability (indicated by a​ decrease in​ the​ reading grade level) of​ the​ document. if​ editing increases the​ reading grade level,​ ask your editor why that score has changed.

What to​ Do

Provide your editor with the​ information that will enable him/her to​ do the​ best job. Here are some things to​ tell your editor:

* the​ intended audience for the​ User Document

* Tell your editor that you want an​ informal style of​ User Document

* What style manual or​ guide to​ be used in​ editing

* Scheduling and progress of​ the​ project

* Format for sharing and editing the​ text (make sure the​ editor can read your electronic documents -- do this when you hire the​ editor)

(Whenever you are dealing with someone outside your organization,​ you must have a​ signed non-disclosure agreement. This is​ in​ addition to​ any other contractual items between the​ outsider and your organization.)

Get to​ Know Your Editor

Your editor is​ NOT your school teacher. in​ your school days,​ your teacher-as-editor was a​ judge. Your goal was to​ impress your teacher with your writing. You were working for a​ grade. Thus you may have come to​ fear your editor.

Change your thinking! Now,​ your editor is​ on​ your side. Your editor will work with you to​ produce the​ best possible writing. You will not have to​ worry excessively about grammar. You goal is​ to​ get the​ information "on paper" as​ clearly and completely as​ you can. Your editor will suggest changes to​ polish the​ text.

So don't fear your editor. Make your editor part of​ your writing team.

Love Your Editor

Hire Your Editor Early in​ the​ Project

Hire your editor early in​ the​ life of​ the​ project. There are at​ least two benefits to​ hiring the​ editor early:

* First,​ your editor will be prepared for the​ editing task. He/she will have had time to​ get to​ know the​ product,​ target audience,​ and your organization's style guide.

* Second,​ your editor can help you with your writing,​ as​ I describe below...

Let Your Editor Help You

If you run into problems about how to​ write something,​ call on​ your editor. Most likely your editor can provide an​ effective wording to​ get you around your block. That's one reason why you got the​ editor on​ the​ project early. Here's another...

A Recommendation

I recommend that you work on​ small pieces of​ the​ User Document,​ and circulate these small pieces (rough drafts) to​ the​ development team for comments. Then use their comments to​ improve the​ writing,​ and re-circulate the​ improved material. Continue this for a​ few cycles. I call this "Iterative,​ Interactive Writing." This is​ an​ effective method for writing quickly and accurately.

If you feel uncomfortable about circulating rough drafts to​ the​ product development team for review,​ here's a​ solution. Have your editor perform a​ quick edit of​ the​ rough draft before you circulate it​ for comments. Your "drafts" will look quite good,​ and the​ development team will concentrate on​ the​ content,​ not the​ wording or​ grammar (and comments about content are you want from the​ team).

The Bottom Line

Don't think of​ your editor as​ an​ enemy lurking at​ the​ end of​ your document production path. Instead,​ realize that your editor can be a​ valuable member of​ your writing team,​ and is​ on​ your side. He/she should:

* Be brought onto the​ writing project early

* Be kept aware of​ the​ status of​ the​ writing project

* Be used as​ a​ writing,​ as​ well as​ an​ editing,​ resource

TIP: it​ is​ much more enjoyable for the​ writer (you) to​ work with "marked-up" electronic documents,​ rather than marked-up printed documents. Investigate your word processor's "multiple reviewers" capability. to​ employ this capability requires that you and your editor use the​ same or​ compatible word processing software.

NOTE: I am not an​ editor,​ nor do I represent any editors. But as​ a​ writer,​ I value editing.




You Might Also Like:




No comments:

Powered by Blogger.