Re: Programmers as writers

Subject: Re: Programmers as writers
From: Susan Harkus <susanh -at- CARDSETC -dot- COM -dot- AU>
Date: Tue, 22 Jun 1999 08:48:38 +1000

I don't think this is an either programmer or writer issue.

Recognising the skill associated with good document development, many firms
now bring in consultants to train programmers and other staff to write well
(= analyse, design and develop text). They also fuss a lot about corporate
templates, something I was rather sceptical about until I saw our software
developers working with an extremely well-designed and "prompting" program
design template.

I see one of my roles in our organisation as mentoring and empowering
others to write effective technical documents. Sometimes I "work" them to
establish the initial information scope and content groupings.

Analysis and design is the challenge, as Karen indicated, "Some of my edits
dealt with style and mechanics, but there were also a lot of content
issues--the programmer is clearly not trained in writing requirements. I'm
sure it would have taken far less time all around if I had written this doc
myself." If the scope and grouping is inappropriate, no amount of editing
by a writing professional can bring it up to a level of effective
communication.

However, there is SO MUCH writing in any organisation these days that to
assume it all has to be done by technical communicators is a little
unrealistic. We have to explore collaboration and mentoring options. For
example, I know there was a technical writing with mentoring workshop at
the 1998 STC conference.
Susan Harkus






Peterson Karen <Peterson_Karen -at- PRC -dot- COM> on 22/06/99 07:53:49 am

Please respond to Peterson Karen <Peterson_Karen -at- PRC -dot- COM>

To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
cc: (bcc: Susan Harkus)
Subject: Programmers as writers




Dear Techwhirlers,

Our programmers do a lot of documentation, such as functional design specs.
Because these docs go to our client, they must conform to the clients'
style.

I just spent quite a while peer reviewing a programmer's doc. Some of my
edits dealt with style and mechanics, but there were also a lot of content
issues--the programmer is clearly not trained in writing requirements. I'm
sure it would have taken far less time all around if I had written this doc
myself.

Should we "let" programmers write documentation? Should we just make sure
we
get involved as editors? I've had a lot of luck with getting the
programmers
to come to me with questions, but I don't think our clients should be
wasting money paying a programmer to write.

I've searched the archives about this without much luck. What are your
experiences/opinions?

Thanks so much,
Karen


From ??? -at- ??? Sun Jan 00 00:00:00 0000=


From ??? -at- ??? Sun Jan 00 00:00:00 0000=



Previous by Author: Single-sourcing tool - UNIX solution too
Next by Author: Re: Navigation in online help
Previous by Thread: Re: Programmers as writers
Next by Thread: Naming Convention for Manuals


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


Sponsored Ads