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. Thus these early notes should be related to where you will get your information: things to read and people to contact, and a product to play with.
Read this entire Section of the Course now, and begin implementing the suggestions that I present here.
Remember: There is always something to do or learn on this Documentation project. Don't stop working while you are waiting for something else to happen.
O Learn about and understand why you should use your word processor's "styles" for formatting your document. "Styles" (or whatever your word processor calls them) are sets of characteristics such as a structure and formatting. For example, Heading (level) 1 is a style, Heading 2 is another style, and so are Title, Body Text and others. When you apply a style to a block of text, two things happen: (1) the formatting of the style gets applied to the text and (2) the word processor will be able to understand the structure of the document. The word processor's table of contents tools will use the higher-level headings (1 through perhaps 4) to automatically generate a table of contents.
O Learn to use your word processor's outlining capability. The outliner automatically assigns styles to the headings in your document. Design your User 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 Reader
(your Components Readers, in our Course).
The Reader can make revisions to the document, and sends it back to
the author. The author can then
choose to either accept or reject each revision provided by the Reader. You will have to be able to deal with
revisions from multiple Components Readers for each Component of the
Start gathering information about these items: We will work on the User Document Specifications in a later section of this Course (where you begin to create your User Document).
Learn about the product
O Learn about the intended Users and Readers of the User Document you are writing
O Learn about the goals of the document
O How is document to be published
O What are you to deliver on this project?
Product release timeline/schedule
As early as the relevant information about their components of the document become "firm" these people should be brought into the project, and provided an overview of the project, and their roles in the project.
Pretend that it is 10 years from now. You or someone else must re-write the User Documentation for the product you are now working on. You or someone else must be able to contact those who worked on the original project or the people who replaced them. You may need to ask them questions, or at least to find the notes and other background material related to the document that they produced. You must keep of record of everyone who worked on the project (for the product itself and for the User Documentation.)
The people who worked on the project include (there may be others, include them in the list):
O Project Manager
O Who will approve each portion (Component) of the User Document, and who will approve the final User Document
O Project Team
O Sources of Information
O Publisher of Document
Enlist as many of the people as you can on the Project to be your Components Readers.
You should keep (for yourself and the entire project team) the following information in the User Document Specifications document. It should have an entry for every person inside and outside the organization who is affiliated with the project, and these data:
O Full Name
O Role in the Product Development
O Organization and Position in the Organization
O E-mail address
O Telephone contact address
O Office address
O FAX number
O Any other comments about their expertise and what they did on the project.
Start a list of everyone related to the project. You can keep the list using a word processor, spreadsheet, or dedicated address-book software and in your e-mail program. Use whatever method you are used to using (a computer program is best, as it permits you to edit the list, and to share it with the other members of your project team).
Include the information I suggested above about each participant. The goal is to know who worked on the project, their role in the project, and how to contact them.
Keep the list up to date.
It is always a good idea to use software that can export
and import information in ways that is transferable to other software. Examples of such export/import formats
include: (comma) delimited, fixed-width text, rich text format (word
processing), plain text. I strongly
believe that any software that does not support such data transfer are truly
limited and will eventually cost the User in time and effort if the User
decides to move to another software program or platform.
Let’s call the person that either hires you or assigns you the task of writing the document (or a portion of it) your “initial contact.” This person said something to you like this: “You have been assigned (or hired) to write a User Document for Product XYZ.” There are several things you must ask of your initial contact, and you must carefully note the responses.
Ultimately, your initial contact must provide you with (or put you in contact with someone who can provide you with):
Access to literature
about the product
Access to the members
of the project team.
Access to the product
itself or a mockup of the product.
Of Course 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 the primary client for your writing services. That person will be what we call “initial contact.”
I'll mention this again later. We speak in the business world of our "client." That is usually the person or organization
that hires and pays us. It's the one
we are working for. On the surface,
you can use that definition of your client.
Get whatever materials you can read about the product and about the project. Read all the material you can get. It will prepare you for the interactions you will have later with the project members.
You early investigations should be aimed at answering these questions:
Description of the Product.
Audience for the Document and the
3. Goals of the Document that You are
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 will the other documents in the set cover (so you can refer to them in your document).
5. And of Course, the contact information that I discussed just above. For every question you might have, you must have a source (be that source written, or human) for an answer.
The items on the above list would probably be answered by “higher level” members of the project team. Perhaps your initial contact 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 (Rich Text Format) that you can download. It is User Document Specifications.rtf
Document all of this information. We'll discuss the idea of documenting your documentation in a short while.
Very early in the documentation project you should ask your initial contact about these writing-mechanics topics:
What are the Organization’s (your company, group,
division) Documentation Guidelines and Standards
What are the Legal Guidelines for the
How the document and components of it are to be approved
by those responsible for the product and its documentation.
What writing and outlining software does the
· Select and get a Style Manual; we will discuss this later.
How will the document be published
Keep track of all this information. You will organize it and add to it as you document your documentation project. We'll describe documenting your documentation project later in this Course.
To the person assigning the project: When you assign the project to your writer, make sure that you have gathered the information that they need to have in order to begin work (as described here). The writer will ask you for the information sooner or later, so they might as well have the information that they need when they start the project…doing so will save time.
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 initial contact how you plan to write the documentation. You will be writing the document in pieces (which are logical topics or modules), and provide them to others on the team producing the product for comments. Look over this Course, especially the Steps in writing, and produce a simple description of how you will write the document. Such a description might include the sections of the document and the order in which you will work on them.
Also (unless you are a professional writer, in which case you will do most of the editing yourself) tell the people that have selected you for the project 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 Readers ("experts" within the project team or marketing) to evaluate them on completeness and accuracy. You will ensure clarity of the writing in the 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:
O 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.
O 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.
I believe that information smoothes the paths we take through life. (Whew, sorry about the philosophy.)
Gather information from all possible sources about the product.
Learn as much as you can about the product. Become the expert on the product, especially the use of the product (if possible). Do this by
O Read about the product and any related information
O If possible, get some hands-on experience with the product, and
Later you will expand your information gathering to include these sources:
O Then by contacting others involved in the development of the product with your questions
O Using the product, or products like it. If this is not possible, then talk to the people who use the product or products like it.
Learn, learn, learn! Become the expert about the product and its documentation.
(And keep doing it as long as you are part of the project.)
Add the information gathered about the product and the players to your User Document Specifications.
Publish this information in your Internal Publication Medium. Thus it will become a resource for all of those on the project.
By now you should have set up your Internal Publication Medium. Use it to internally publish the information related to the User Document project.
(c) 2006 Igetitnow! Training, Inc.