Re: This too is technical communication

[Ned Bedinger <doc -at- edwordsmith -dot- com>]

Chris Borokowski wrote:
> The problem is that some central authority or voice
> can really help organize a disparate profession. Some
> see certification as the answer.
>
> I would suggest that before we even worry about that
> debate, we start praising the good tech writing out
> there and making people aware of it. 

Aiieeee! First, we'd have to be able to say what is good technical 
writing. We can't swing a cat without hitting someone's definition that 
includes add-ons.

I guess now is a good a time to make my stand about tech writing and its 
place in the scheme of things. I have an example in mind, and FWIW, this 
example is about a documentation team effort in which the tech writer's 
role is limited to writing. The TW role is not responsible for 
illustration, layout, typesetting, publishing, coding, and whatever. It 
has been donkey years since anyone in tech writing (or anyone who uses 
tech writers) has refered to The Work and our responsibilities in such 
limited terms, but I think the limited role is the touchstone of tech 
writing, and any definition of good tech writing or our role really 
actually should try to hang with that limited sense of tech writing.

I have some typewriter repair manuals that are gems of technical 
writing--the tech writer and illustrator created lucid overviews, 
problem descriptions, and procedures. They obviously worked very closely 
with the engineers, and the engineers obviously knew how to approach the 
typewriter as a comprehensible bunch of systems. The editors knew the 
subject and checked the content carefully. The book designers did an 
exceptional job in laying out the pages, and the publishers put it all 
in a hole-punched lay-flat binding on paper that withstands years of 
usage in the shop.

I've worked through these manuals, and I can't recall ever being stumped 
by an instruction that was ambiguously worded or insufficiently 
illustrated, or a procedure that was inadequately analyzed before being 
written up. It was not simply tech writing that produced good 
documentation. The teamwork (writer, illustrator, editor, engineer, 
designer, publisher) produced the high quality of this exemplary 
documentation. User would write their names on their copies and put them 
carefully away at night. They could fall in love with these manuals as 
the perfect and comprehensive match for their needs. The manuals were a 
big selling point in the marketing of these typewriters by a company 
that was known as a salesman's company--I'm describing the manuals for 
the IBM Selectric.

When today's tech writer takes on all of those responsibilities that 
once were allocated to an entire team, the focus on quality is strained, 
if it exists at all. If I thought it would do any good, I'd dig in my 
heels and demand an editor, illustrator, and publishing assistance for 
most tech writing projects. I'd be standing on my desk yelling "Do I 
have to do it all??" But my employers these days have already grasped 
the nature of their tech writer. All they have to do is yell back, 
"Can't you?"

I, like most tech writers I know, find that question intriguing. As much 
as I wish tech writing could be a sane and clearly defined, limited 
role, I am one of those who don't think about it very long before 
responding, "I think I can. I'll try." I know I'll have to rationalize a 
lot of things that eventually go wrong, but in the final analysis, they 
seem content with what they get, probably because people have become so 
accustomed to lame documentation; no one seems to have any power to 
demand better, even while we all are acutely aware that good 
documentation is moving out of reach of tech writers.

Here endeth the screed.

Ned Bedinger
doc -at- edwordsmith -dot- com


> I don't know how
> we can do it for proprietary stuff (samples?) but if
> you encounter an excellent manual or guide or
> description, maybe it's time to just make a links list
> and praise the heck out of it.
>
> --- John Posada <jposada01 -at- yahoo -dot- com> wrote:
>
>   
>> Funny how a number of people keep coming back to
>> that as a solution
>> when there are problems they cannot figure out how
>> to solve in other
>> ways.
>>     
>
>
> User Interface design blog
> http://user-advocacy.blogspot.com/
> Code::Design::UI::Consulting
> http://www.dionysius.com/
>
>
>        
> ____________________________________________________________________________________
> Looking for a deal? Find great prices on flights and hotels with Yahoo! FareChase.
> http://farechase.yahoo.com/
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Create HTML or Microsoft Word content and convert to Help file formats or 
> printed documentation. Features include support for Windows Vista & 2007 
> Microsoft Office, team authoring, plus more.
> http://www.DocToHelp.com/TechwrlList
>
> True single source, conditional content, PDF export, modular help.
> Help & Manual is the most powerful authoring tool for technical
> documentation. Boost your productivity! http://www.helpandmanual.com
>
> ---
> You are currently subscribed to TECHWR-L as doc -at- edwordsmith -dot- com -dot- 
>
> To unsubscribe send a blank email to 
> techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
> or visit http://lists.techwr-l.com/mailman/options/techwr-l/doc%40edwordsmith.com
>
>
> To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
> http://www.techwr-l.com/ for more resources and info.
>
>
>
>   

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

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info.