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.

BONUS : New Technical Writer: The Four Dimensions Of Your User/reader

OVERVIEW

To create an effective User Document, the writer must know who he/she is writing for. This article presents four dimensions (Skills, Attitude, Knowledge and Experience) for describing the User of your product (your Documentation Reader), and how to build a Persona that turns your generic User into an almost-real person. The article stresses the need to actually USE this information when structuring and writing your User Document.

GETTING INFORMATION ABOUT YOUR USER

The marketing department or product development team should be able to tell you who the intended User of the product is. (If they cannot, then the product is in big trouble.) Ask them to provide you with a complete description of the User. Ask them if their description can be make less strict (requiring fewer skills, ect.) and thus be applicable for a wider audience. Ask them how sure they are of their intended Users.

Ask them if they created a "Persona" (see below) to design the product. If so, ask them for the description of that Persona.

We will use this information to analyze your User in four dimensions. We will then re-build the ideal User into an almost-real person, who you can use to help design and write your User Document.

Timing: My estimate is that if the communication paths between you and the marketing and development teams are effective, then you should be able to complete this series of steps in a few hours spread over several days. This description of your User/Reader is an essential element in structuring and writing your User Document.

THE FOUR DIMENSIONS OF YOUR USER (Reader of your Document)

Four dimensions define your User/Reader. These dimensions are:

* Skills

What skills do you assume that your Reader must have in order to understand your User Document? (These are the skills that you assume that they have when they START to read your User Document... not the ones that you will teach them in the User Document.)

In a classic example of failure, a company that taught software programming did not specify that its students had to know how to use a particular computer word processor. As a result, students spent 80% of the class time learning how to use the word processor, rather than learning to write programs. The class was a failure.

List the skills that you expect your Reader to have.

* Attitude

Your Reader's attitude is almost always a combination of anger (impatience at having to read this stuff instead of using the product), and fear (something is not working the way your Reader expects it to). Write with compassion for your Reader. Are there other attitudes that may affect how your Reader uses the product and your documentation?

* Knowledge

What information do you expect the Reader to have when they read your User Document? Is there something that you expect your readers to understand or to have to figure out for themselves? If there are such items, then you should tell your Reader where to get the needed background information.

* Experience

Skills plus practice, yields experience. Are there any experiences that you expect your Readers to have, so that they can understand how to use the product or understand what you are writing? BEWARE of your Readers' experiences that may negatively affect how they use your product. One example is a product that radically changes the way that the User currently does things. Devote some space in your User Document to overcoming these problematic experiences.

WRITE FOR THE SAKE OF YOUR READER

These four dimensions spell out the word "SAKE." This reminds us to write for the SAKE of our Readers. You use these four dimensions when generating the topics for your User Document, as well as reviewing the material that you have written. These are topics for other articles in this "New Technical Writer" series.

Make sure that you tell your Reader about any SAKE assumptions that you make about them. Thus if you assume them to have a special skill, such as "welding steel" then tell them your assumption early in the User Document. If possible, tell them where they can get the background SAKE items that they might need. For example, if you assumed that your Reader has the skill to identify a certain bird, then tell them were to learn to identify that bird (perhaps with a link or reference to a birding authority).

You want to avoid situations like the one in the example above: the unstated requirement for knowing a specific word processor that ruined a programming class. Is the assumption that everybody knew how to use that esoteric word processor a reasonable one? The course developers should have checked with their sales department, since they sold the course to students who could not possibly have known about that esoteric word processor.

You really must clearly state (early in your User Document) any out of the ordinary assumptions that you make about your Reader.

YOUR READER AS A REAL PERSON

From the SAKE dimensions, and from the descriptions of the typical User of the product that you got from the marketing or development teams, you will create a real-as-possible person to represent your typical User. Such a representation is called a Persona in the product development industry. The Persona is also your User Document Reader.

If the marketing and development teams use a Persona, and they provided a description to you, then use their Persona. You may have to add some description to it.

If you have to create a Persona, follow these steps (overview):

1. Imagine the generic User of your product.

2. Focus on this User. Describe the User. Think about his/her background, education, family, hobbies, interests. The goal is to make your generic User as tangible as possible.

3. Perhaps give the User a name, and even spend a minute or two to find a photograph of this Persona.

4. Evaluate for yourself if this Persona is a good representation of the User. Make changes as necessary.

Think about how the Persona got your product (for example, did they purchase it, did it come bundled with some other product, was it a gift, etc.). Think about what they are most likely to want to do with your product.

Later we will use the Persona to help define the topics of the User Document, and to help you write the actual text.

CHECK

Once you have generated the SAKE items and the Persona, write them out, and let members of the product and marketing teams check them for accuracy. "Accuracy" means "how closely your Persona coincides with their (product and marketing teams) view of the product's User." Discuss these points and make modifications as needed.

USING YOUR READER

Unfortunately most courses and books about technical writing stop here in their instructions about "knowing your Reader." These courses and books expect you simply to keep your Reader in mind when you write.

But you can and should do much more with the description of your Reader. The Persona will help you structure the information in the overall User Document; it will also help you write each of the topics.

The SAKE dimensions will help you as you revise your writing. Here the SAKE dimensions will

* help you avoid using language your Reader might not understand, and

* help you avoid jumps in your writing that your Reader will not be able to make.

Other articles in the "New Technical Writer" series will describe how to use your Persona and SAKE dimensions to design and write your User Document. See the "Resources" or "Author Information" section of this article to find links to related articles.