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 EditorSome of the changes that an editor might suggest could make the User Document more difficult for your Reader to understand.
Improving Your WritingOnce your editor has gotten past the basic mechanical editing tasks of:
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. EruditionAnother 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 (shouldn't) be avoided. If you think about it, most people reading the User Documentation for any product are under some form of stress:
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:
(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 EditorYour 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.
Let Your Editor Help YouIf 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 RecommendationI 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 LineDon'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:
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.
Great Technical Writing: The User-Product Life Cycle - A Documentation Tool
The User-Product Life Cycle (U-PLC) is a powerful tool for the User Document writer. Use the U-PLC to generate the high-level topics for your User Document.
Great Technical Writing: Tell Your Users What to Expect
In your User Documentation, you direct your Reader to perform tasks with your product. If you don't tell your Reader what to expect when performing those tasks, you will have a baffled Reader, resulting in dissatisfaction and expensive calls to technical support.
New Technical Writer: Conquering the Fear of Writing
Stepping into the role of a technical writer can be daunting, especially for those without a writing background. The task of creating User Documentation for a new product might stir up fear and anxiety, reminiscent of school days filled with writer's block and critical evaluations. However, writing for a user manual is a unique process that differs significantly from academic writing. This article aims to guide new technical writers through the process, providing strategies to overcome anxieties and produce effective documentation. With the right approach and resources, anyone can craft clear and helpful user guides.
