A "new understanding" about tech pubs

[Andrew Plato <gilliankitty -at- yahoo -dot- com>]

"Shea Michael EXT" wrote...(in another thread)

> Ah, but as you said yourself:
> 
> "...the guy who actually has to use the software...is NOT the guy who 
> decided to buy it."
> 
> And as you pointed out, this guy isn't consulted when the decision is made
> to buy the software. So from the standpoint of trying to make a sale, the 
> documentation ought to be directed at the VP making the purchasing decision. 
> (Assuming he or she even looks at the docs. All the VP probably does is 
> sees "docs included" on a Powerpoint slide of product features.) 
> Unfortunately this does not lead to good documentation in the empirical 
> sense. 

But it does in the economic sense. 

Pleasing the "user" is not always the primary goal documentation. A good doc
set can also be a good sales tool. It proves that the organization has a handle
on their own technology. 

I read A LOT of user docs for security products. I am evaluating a product
right now. The writers at this company are pretty savvy and it shows. They
clearly have command over their technology. They understand the benefits,
value, and use of their product. As such, I have a lot more faith in this
company and as such, I am going to sign a reseller agreement with them. 

This is in comparison to another product I was evaluating last month.  The docs
were the standard tech doc crap: pages and pages of instructions with virtually
no context or explanation. The writers took 10 pages to document every menu
item.  

The writers clearly did not have command over the topic and as such, I am left
to believe that the company doesn't really have their act together. I will not
be signing a reseller agreement with that firm. 

A lot of companies flip through the technical manuals to get a feel for the
competence and capability of a potential supplier or vendor. I know for an
absolute fact that the sole reason I have been able to close deals with
customers was because I had documentation that impressed executive and
technical staff. The docs were my sales tool. They were the proof that I
understood what I was talking about. 

This should be encouraging to those of you who think I hate tech writers. I
believe tech writing can be one of the most important and valuable aspects of a
organization. Done right and properly integrated into the larger scheme of an
organization, technical documentation can not only help users it can sell
products and impress customers. 

However, in order to do this, there must be a "new understanding" about
technical publications. 

1. The tech writers MUST be very technically and business savvy. 

2. The organization MUST understand how to market and sell their products using
docs as an example of their capabilities.

3. The traditional mode of "we just pretty up text" must be totally abandoned. 

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

5. Docs must have message and context. They must deliver more than just
instructions. They must education and demonstrate the value and capabilities of
the technology. 

6. Tools, style-guides, 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 else in the organization cares
that a writer can make a cool style in FrameMaker. The ability to use a
documentation tool with proficiency is treated as a given and extremely small
amount of time and energy is devoted to tool issues.

7. Writers are expected to deliver docs that 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" approach
is insufficient. Other questions like "what are the benefits of this
technology?" and "what concepts will help the users make the most out of this
tool?" need to be asked and answered in the documentation. 

Naturally there are a lot of other issues to consider. But done properly, tech
pubs can become a valued resource and not an annoying necessity. 

Can this work, yes. I've seen it happen before and it takes a lot of effort.
But the pay off is worth it. Tech writing becomes a highly valued resource in
the organization and warrants a great deal of respect. I have build this
respect in some firms. 

Andrew Plato 




__________________________________________________
Do you Yahoo!?
Yahoo! Mail Plus - Powerful. Affordable. Sign up now.
http://mailplus.yahoo.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
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 http://www.ehelp.com/techwr-l

---
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
http://www.raycomm.com/techwhirl/ for more resources and info.