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