Co-operation between technical writers and programmers

[Ollie Cornes <ollie -at- XARA -dot- CO -dot- UK>]

Hi crew,

I am currently involved in discussion over the level of co-operation
there should be between the programmers writing an application
and the technical writers involved in documenting the product,
most particularly the online help.

I have only a couple of years experience on technical writing
and this is limited to the one product, so I'd like to describe the
problem here and see if it rings any bells with anyone else.
I'd love to know how others have approached this.

My feeling is that when a programmer (I use the term flexibly and
include design work in it) designs or implements a feature or
makes a change they should be very aware of how this will affect the
documentation. There may be examples of areas where something
is very hard to document (often a good reason for a redesign IMHO).
It also makes sense for the programmer to understand how the
help connects to their work so they can tailor their work to how the
help is implemented and make suggestions as to how the help can
be improved to fit their intention with a design. The end result is then
likely to be a well documented user interface component or area
rather than "a user interface component" and "a help page".

The other week I was faced with a good solid design document for some
changes to a project, it contained pretty much everything I needed
Though as the programmer concerned had not even glanced at the help
for this area of the program he had no recommendations or suggestions
to make. The "Documentation Changes" section of the documented
contained one statement - "Document the changes".

Basically, I am very much against any ethos like this which suggests a "oh,
well yeah, the technical writers are doing the help, they can sort
it out". The sort of "oh, yeah, the help. That'll be stuck in at the end
just before we ship". I think maybe there's a pride/ego thing here
as well that the help is often seen as a minor part of an application,
but looking beyond that I feel the help is not being given the attention it
deserves.

I feel that an application is a unit and the help and the program's interface
are so closely linked that the two pieces of work (although very different
in nature and purpose) need to be done in a very close fashion.

The opposing view I am attempting to counteract is summed up as
"writing the help is the technical writer's job, work it out from the
design documents, there is no need for programmers to be involved
in the help".

We operate under limited resources, so reviews are few and far between.
In my view this makes it even more important to get as much feedback as
possible and the programmers are potentially my best source.

I think there must be a balance in here somewhere, but where..?

Regards,

Ollie.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Post Message:	TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Get Commands:	LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU with "help" in body.
Unsubscribe:	LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU with "signoff TECHWR-L"
Listowner:	ejray -at- ionet -dot- net