Si vous n'ĂȘtes pas Ă l'aise avec l'anglais, utilisez ceci :
Cet outil vous fournit une traduction automatisée en français.
New Technical Writer First Things To Do On The Project
OVERVIEW
You, a non-writer, have just been assigned to write the documentation for a product your company produces or markets. You may be stressed out about the assignment. Fear not! This article will get you started on the path to writing a successful document.
QUESTIONS AND NOTES
As soon as you get assigned to the documentation project you must begin to take notes and ask questions. The major goal of this early information gathering is to gain access to the sources of information that you will need in order to write your document.
TIP: There is always something to do or learn on a Documentation project. Don't stop working while you are waiting for something else to happen.
LEARN PROPER USE OF YOUR WRITING TOOLS
Do NOT get immersed in new technology. For most companies and for most documentation projects, investing the money and time to learn a Content Management System or exquisite document writing software are not worth the effort. Documentation writing is often the tail end of a project, and you will have no time to learn new technologies. Instead learn to get the best from your existing word-processing tools.
* Learn about and understand why you should use your word processor's "styles" for formatting your document.
* Learn to use your word processor's outlining capability. The outliner automatically assigns styles to the headings in your document. Design your Document using your word processor's outlining capability.
* Learn how to use your word processorÂs revision system. The revision system is a facility where the author writes a document and then sends it to a reviewer. The reviewer can make revisions to the document, and sends it back to the author who can choose to either accept or reject each revision.
Technology comes second. Our goal will be to produce a great document, providing the:
* content (the information that your Reader needs or wants) and
* effective access to that content.
DOCUMENT ALL PEOPLE ON THE PROJECT
The people who are working on the project include (there may be others, include them in the list):
* Project Manager
* Those who will approve the parts of the Document, and who will approve the final Document
* Project Team
* Contacts
* Marketing
* Sources of Information
* Publisher of Document
* Editor
* Indexer
Keep this information about each member of the product and documentation team:
* Full Name
* Role in the Product Development
* Organization and Position in the Organization
* E-mail address
* Telephone contact (FAX number)
* Office address (if there is a company-wide directory, get the address from there, when you need it)
* Their expertise and what they did on the project
* Any other relevant information
DO IT NOW: LIST THE PLAYERS
You can keep the list using a word processor, spreadsheet, or dedicated address-book software and in your e-mail program.
Keep the list up to date.
YOUR PATRON
LetÂs call the person that assigns you the task of writing the document (or a portion of it) your "Patron". This is the person who is responsible for ensuring that the documentation gets produced. There are several things you must ask of your Patron, and you must carefully note the responses.
Ultimately, your Patron must provide you with (or put you in contact with someone who can provide you with):
* Access to literature about the product
Includes marketing, design, concept information, documentation for similar products; in short, anything they will let you read that might be related to the product. Once you get the written documentation, read as much as you possibly can about the product. A goal is to become the expert about the product.
* Access to the members of the project team.
Not only the names and contact information, but also provide the Âclout to get these people to provide information to you. This is vitally important!
This access must include the marketing and design teams. They can tell you about the potential Users of the product.
* Access to the product itself or a mockup of the product.
So you can gain some hands-on experience with the product.
Access to Users of similar products; access to potential Users of this product (or information about them)
If you have been hired by, for example, the Human Resources Department of the company, then Human Resources will have to direct you to the person on the project who is your Patron. Your Patron is not your client.
In the business world we speak of our "client." That is usually the person or organization that hires and pays us. It's the one we are working for.
However in reality your client is your Reader. It is your responsibility to do the best job for your Reader. If it's necessary to go against the judgment of your Patron then you must be prepared to convince your Patron of the merits of your way of doing the work.
Read all the material you can get about the product and the project . It will prepare you for the interactions you will have later with the project members. Be prepared by knowing as much background information as you can before you have your first information gathering session (meeting).
Ask: "What can I read or do in order to get the background on this topic?"
Even if you are the developer, there are things you need to learn. One of the most important is concerns the characteristics your potential User.
Your early investigations should be aimed at answering these questions:
1. Overall (brief) Description of the Product.
What does the product do for the User;
How does the product change the way the User currently does things.
2. Intended Audience (the Users) for the Document and the Product
This is the "target market" for the product; information about who will use the product. This information could come from the marketing and design groups for the product. Ask them: "Tell me about your potential User of this product?"
3. Goals of the Document that You are Writing
This is the "scope" of the document what is your document supposed to deal with regarding the product. See the next item on this list, item 4. Is your document to be a User Manual, Reference Manual, Setup Guide, or a combination of these?
4. Are there to be any other User Documents to be produced that are related to this product? That is, is the document you are working on a portion of the User Document set that the organization will produce for the product? If yes, what are the other documents in the set (so you can refer to them in your document)?
5. The contact information that I discussed just above. For every question you might have, you must have a source (be that source written or verbal) for an answer.
The items on the above list would probably be answered by Âhigher level members of the project team. Perhaps your Patron can answer them; if not, he/she must guide you to where (or from whom) you can get the answers. These are the first things you will write about in your User Documentation. Get this information early in the project.
In short, you need to get both written documentation about the product and contacts who you can ask to provide more information.
Eventually you will enter this information in a word processing document that you can share.
Document all of this information.
ASK ABOUT MECHANICS
Very early in the documentation project you should ask your initial contact about these writing-mechanics topics:
* What is the time frame for producing the documentation. When do you have to have the writing finished so that it can be edited and published.
* What are the CompanyÂs (your company, group, division) Documentation Guidelines and Standards
Look over some acceptable documentation produced by the Company
* What are the Legal Guidelines for the documentation
You will need this for disclaimers, safety information, and the copyright notice
* How the document and components of it are to be approved by those responsible for the product and its documentation.
Ensure that you know when and how the components or stages of the document are to be approved. Know
who is to approve your writing. Stay in close contact with those people.
* What writing and outlining software does the Company use
Your software should be compatible with that of the Company
* Get a Style Manual
A style manual is a guide for selecting phrases. It sets down writing customs for your industry or Company. For example, the style guide for the indexing community says that the plural of "index" is "indexes," not "indices." A mathematical style manual would select "indices" as the plural of "index."
If your company has adopted a style manual, use that one, if appropriate to the product. If not, search an on-line bookstore for "Style Manual" or "Style Guide" and your industry, such as "Style Manual Mathematics".
* What are you to deliver on this project?
* How will the document be published
Printed, on-line, Adobe Acrobat PDF, context-sensitive help, XML (so it can easily be manifested in any display medium)
Keep track of all this information. You will organize it and add to it as you this documentation project moves forward.
GIVE SOME INFORMATION
You should give everyone your contact information so they can get in touch with you. You might consider using your business card, and writing on it that you are writing the User Document for whatever product. Make it easy for your contacts to get in touch with you. Ensure that you have your contact information in any e-mails or copies of the document that you send to others.
You should also tell your Patron how you plan to write the documentation. You will be writing the document in pieces (which are logical topics or modules), and provide the pieces to members of the product team for review.
Also (unless you are a professional writer, in which case you may do most of the editing yourself) make it known that you plan to use someone else to edit your document. Interim materials that you provide might not be edited; you are providing them in order for reviewers ("experts" within the project team or marketing) to evaluate them on completeness and accuracy. You will ensure clarity of the writing in the (later) cycles of editing and revision.
One of my (ideal) goals for you is that you become the focus of all the User-oriented information about the product. You become the resource that others on the project turn to for information.
I believe that you should provide information to those involved (and especially those to be involved at a later stage in the project, such as the indexer) as early as possible in the life of the project. There are several benefits to this:
* They will learn about and think about the product and project. This will happen because people do want to do a good job after all, itÂs their livelihood.
* There will be fewer surprises. People know what is happening with the project, how their roles and timing might change. Encourage your Readers to comment back to you about anything related to your work.
Learn, learn, learn! Become the expert about the product and its documentation.
SET UP AN INFORMATION SHARING RESOURCE
I believe in sharing information...it makes for a better work environment and a better product. Use whatever available technology you have to create (or get created) some kind of resource to share information. This information will be in the form of computer files...nothing magic.
You may be able to use a shared directory on a local network, or a protected area on your company's intranet. Investigate what is needed. Provide read and write access to all the people (inside the company) who are involved on the project.
One of the first things to post is the list of people on the project. Make sure that whatever you post, it is in a form that everyone who has access to it can read (and possibly write) it.
NEXT STEPS
Other articles in this "New Technical Writer" series will assist you as you progress through the writing project. Look for them in the links in the "Resources" section.
BONUS : 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.
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.
