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.
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.
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 processors 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.
* effective access to that content.
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.
Lets 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.
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.
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).
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.
1. Overall (brief) Description of the Product.
How does the product change the way the User currently does things.
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.
* 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.
* How the document and components of it are to be approved by those responsible for the product and its documentation.
who is to approve your writing. Stay in close contact with those people.
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?
Keep track of all this information. You will organize it and add to it as you this documentation project moves forward.
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.
after all, its 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.
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.
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.