The FIRST Things You Need to Do

 

Table of Contents for this Reading

The FIRST Things You Need to Do. 1

Overview.. 1

Learn Proper Use of Your Writing Tools. 1

Learn About the Product, Users, and the Document2

All People Who Interact2

Do It Now: List the Players. 3

Your Initial Contact Leads. 4

Ask About Mechanics. 5

Give Some Information, Also. 6

Learn About the Product7

Do It Now!7

 

 

 

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.

O     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 Document. 
Most word processor Users do not know how to use the revision system that their software provides.  You might wish to create a document about the revision system for your Components Readers.  Remember to tell them what the revision system is about, as well as how to use it. 

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).

O     Learn about the product
Immerse yourself in the product.  Learn everything you can about it.

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?

O     Product release timeline/schedule
How the User Documentation schedule must fit with the product's 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     Contacts

O     Sources of Information

O     Publisher of Document

O     Editor/proofReader

O     Indexer

 

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.

 

Do It Now: List the Players 

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.

But it is NOT a good idea to spend a lot of time setting up such a writing system for a writing project that must be completed as soon as possible.

 

Your Initial Contact Leads

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
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!
You will need contact information such as their telephone number, e-mail address, postal address or whatever is appropriate.  Find out the role of the contact person in the project, and what kinds of questions he/she can answer.

·         Access to the product itself or a mockup of the product.
So you can gain some hands-on experience with 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. 

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 "classical" client (the one hiring/paying you) then you must be prepared to convince him/her of the merits of your way of doing the work.

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:

1.      Overall 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 for the Document and the Product
This is the "target market" for the product; information about who will use the product.  (Learn about the Skills, Attitude, Knowledge and Experience that the Users are assumed to have; we will discuss this later)

3.      Goals of the Document that You are Writing
(Actually I mean 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.

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
Perhaps you can look over some acceptable documentation produced by the Organization

·         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. 
Don’t publish the document only to find that it will not be approved for publication.  Don't release anything for publication until it has been approved (with the approval in writing).

·         What writing and outlining software does the organization use
Your software should be compatible with that of the organization

·         Select and get a Style Manual; we will discuss this later.

·         How will the document be published
Printed, on-line, Adobe Acrobat PDF, context-sensitive help

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.

 

 

 


Resources for Writing Great User Documents: Home

(c) 2006 Igetitnow! Training, Inc.