Users of our documents, programming skills for writers, and other topics

[Jill Shindelman <jill_shindelman -at- yahoo -dot- com>]

Recent postings on these topics compel me to emerge
from anonymity and relate an event that occurred while
I was working on THE ideal job of my long career.

In the 1980?s and early 1990?s, I was working for IBM
in one of their buck-stops-here technical support
centers.  There were several hundred of us in the
group, and the organization chart was structured by
product, not by individual roles or tasks.  We all had
extensive backgrounds in programming and systems
support, and were considered to be key technical
consultants.

We had two sets of constituents:  the branch office
sales teams who needed to get meaningful, detailed
information about new products as they were
introduced, and the product development divisions, who
needed assistance in bringing new products to market
and, in the long run, to learn what product features
were important to real customers. 

Each of us at this center had the same mission:  to
provide the best level of technical support to enable
the marketing teams to promote our products and help
potential customers to use them.  We were also the
intermediaries for customer feedback to the
development divisions.  We were given total
flexibility to use whatever means we felt were best to
accomplish these goals (ah, the long-gone 1980?s).

The technical writing aspect of this story is twofold:
 (1) My own product area was high-speed laser printers
and their associated software (including the document
processing packages DCF, Bookmaster, and Bookmanager,
for those who care) and (2) that my job route of
choice was to work with actual customers, see how they
**really** used the products, and then write
specialized technical bulletins that described what
they were doing in enough detail to permit other
customers to get started on similar projects.

I found this to be incredibly fulfilling work. Time
and again, I was surprised and pleased to find that
not only were actual customers using our products to
achieve business goals, but that they were using them
in ways that had simply not been anticipated by the
development divisions (nor documented in the formal
installation manuals and reference books that
accompanied the products). Even more surprising was
the fact that many customers were doing things that
were very similar to one another, but again, were not
explained in the ?standard? documentation.

The best anecdote of the years I spent in this job was
a typical good-news-bad-news story.  After two or
three years of working with dozens of customers who
had used our hardware and software to implement custom
applications, I wrote an IBM publication that
described these applications in detail and even
included COBOL (gasp) programming examples.

After the book was published, I visited yet another
customer, and I was flattered to see that they had
several copies of my book and one of the programmers
had marked it heavily with yellow highlighter.  I
ventured to ask her if the book had been useful. 
?Yes,? she said, ?but of course no one writes COBOL
like this!? 

The moral to this story?  At least two of them:
1.	To write meaningful documentation, there is no
substitute for working with ?real? users.
2.	Having a programming background can help, but
remember that your core competence is writing, not
programming! 

Jill Shindelman

__________________________________________________
Do You Yahoo!?
Get personalized email addresses from Yahoo! Mail
http://personal.mail.yahoo.com/

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

TECH*COMM 2001 Conference, July 15-18 in Washington, DC
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com


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