RE: A "new understanding" about tech pubs

Subject: RE: A "new understanding" about tech pubs
From: "walden miller" <wmiller -at- vidiom -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sat, 7 Dec 2002 22:32:52 -0700

Andrew provides a number of good rules about tech docs. However, I don't
think that any one of them is specifically a doc issue. Each of these rules
should be applied to engineers, artists, marketeers, etc. of a company.
excuse my paraphrases below:

1. Everyone associated with product in a company MUST be very technically
and business savvy.

2. The organization MUST understand how to market and sell their products
all their resources as examples of their capabilities.

3. The traditional modes of a group does only one thing must be abandoned
(e.g., we pretty up text, we don't write docs, we just right code, we don't
test, we don't talk to marketing, we don't talk to ..., etc.)

4. Everyone must become involved with multiple levels of the organization -
marketing, sales, engineering, executive, docs, etc. This requires the
ability to interact with these organizations effectively.

5. Product must have functionality, message, context, value, and timeliness.
It must deliver more than just
technology. They must educate and demonstrate the value and capabilities of
the technology, as well as provide efficient functionalities in a time frame
that is useful to the customer.

6. Tools and methodologies, and many other time-honored one-off
issues must be pushed WAY into the background. Content, message, and
presentation are pushed WAY up front.
Nobody outside the organization, nor outside the specific department cares
about these decisions (tools and methodologies) as long as they improve
product delivery. If they don't improve product then they are bad

7. Product should be expected to serve multiple audiences and
please multiple levels of the organization. Users are only ONE of the target
audiences. Therefore, the traditional "what do our users want to do"
is insufficient. Other questions like "what are the benefits of this
technology?" and "what concepts will help the users make the most out of
tool?" need to be asked and answered by the product.

Basically, what I want to say is that documentation has the same role as
engineering, marketing, graphic art, etc in creating a product. Often each
of these groups has no idea as to what a product is about. Engineers think
the code is the product. Writers know that the code is not the total
product, but often sneer at marketing. Graphic artists create UI's that are
extremely pretty, but totally unusable in the context in which the tool will
really be used, etc. Nor does each group assume their input needs to be
communicated outside their own group.

Engineers fight for their own toolsets and methodologies. Ask engineers
about Rational product line or using Linux or Perforce or SlickEdit. You
will get the same sort of religious discussion that we have over using
Frame, Word, etc.

Andrew is absolutely right about putting everything under the product. But
its not just writers that have these problems. It is entire companies that
are caught up in their own little worlds.

walden miller

Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from
Find out what all the other tech writers, including Dan, already know!

Order RoboHelp X3 in December and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

A "new understanding" about tech pubs: From: Andrew Plato

Previous by Author: RE: A sobering encounter (So now what?)
Next by Author: RE: Online or print for SDK material?
Previous by Thread: Re: A "new understanding" about tech pubs
Next by Thread: Re: A "new understanding" about tech pubs

What this post helpful? Share it with friends and colleagues:

Sponsored Ads