Summary Report: Justifying a Separate Existence

Subject: Summary Report: Justifying a Separate Existence
From: George Hayhoe <george -dot- hayhoe -at- SRS -dot- GOV>
Date: Tue, 14 Mar 1995 11:06:00 -0400

This is a long message; delete it if you're not interested in the
results of my survey on justifying the existence of a software
documentation group separate from the corporate technical publications
organization.

Several weeks ago, I asked list members who create software
documentation to respond to three questions. Within several days, I
received 26 responses to my request. My thanks to all who took the
time to give me information and their views on the subject.

Summary of Responses
====================

1. Where in the company is your team located (for example, in the
software development group, marketing group, company publications
group, etc.)?

The results here were overwhelming. Fully 20 of the 26 respondents
said they are located in a software development organization (also
referred to as research and development or engineering).

Of the remainder, 4 are located in a customer support organization, 1
in marketing, and 1 in corporate communications.

If this sample is representative (and of course, since the sample was
self-selecting, we can't rely on its accuracy without further
validation and must consider it anecdotal rather than scientific
evidence), most software documentation developers are a part of the
organization that engineers the software that they document. This
probably shouldn't be a revelation to anyone, but I found it quite
interesting since management here at Westinghouse Savannah River wants
to consolidate our separate documentation group with the company
technical pubs organization.

2. What is the ratio of developers to documenters?

There was quite a bit of variation in the 23 responses here (3
respondents either didn't know the ratio or didn't answer this
question). The average ratio was 8.8:1, with a range between 3.5:1 and
20:1.

I found this response quite fascinating also, since my group of 3
writers supports an Information Resource Management Department exempt
staff of more than 300, making our ratio about 100:1. (This department
includes computer hardware, network, and telecommunications
operations; and customer support and training, in addition to software
development.)

3. If your group has been consolidated, have there been any negative
effects on end user? any positive effects on end users?

Very few people answered this question directly because almost no one
had been consolidated. The nearly unanimous response, however, was
that the documenters should be in the same organization as the
developers. Here are some sample responses:

"One thing that made the project go so quickly was being right there
with the developers so that questions got answered quickly."

"[Before we were moved into the development organization,] The Product
developers had felt that they had no say in the documentation . . .,
so they didn't review carefully or even give detailed opinions. This
was news to us. . . . Since we've moved to Product Development the
developers have given tons of input on documentation. Spent
considerable time on reviews. And have shown an amazing willingness
(compared to before) to participate in reviews."

"As a part of the team, the programmers have more respect for me and
my contributions to the development effort than they would if I were
an intruder from another department."

"We feel like part of the development team now, whereas before, we
were 'those guys in pubs down on the fourth floor.'"

"Doc and code are companion pieces that comprise the core of a
product. It made sense to us that the people who generate these pieces
be bound together."

". . . better understanding of our products helps us develop better
deliverables . . . . Previously we basically communicated what the R&D
people told us. Now we play a much more active role, checking and
testing the product. . . . By constantly encouraging/nagging the R&D
people to make it better, we get a better product. Because we're part
of the team, they listen to us."

". . . we are all worried about losing 'easy access' to information,
and think it will slow our productivity" if we are moved away from the
development teams.

". . . when we were moved to other areas of the building,
communication really suffered. It wasn't that it took us longer to
find out the information we needed from the developers, it was that we
didn't find out the information at all. Since we weren't always
hanging around them, it didn't occur to them that they needed to tell
us things, even when we made a specific point to visit them and ask
questions about what was new."

Since being moved to the development organization, "Our input is being
included early on in the process so we can assist in creating a
product that overall communicates more efficiently with the user. This
of course should help the users do their work and should cut down on
the number of 'page' we documenters must create in support of the
product."

Finally, Susan Self pointed out that in _Managing Your Documentation
Projects_, JoAnn Hackos describes that enlightened companies involve
technical communicators with the product developers from the beginning
as parts of a cross-functional development team. It not only makes the
documentation process easier, but it also helps avert user interface
disasters before they happen. (Thanks for the reference, Susan!)

There were a few dissents from this consensus. One person observed
that writers can lose their focus and identity, and that they can
become slaves to managers who don't understand how to manage writing
projects. Another noted that being more consolidated would help avoid
schedule conflicts and miscommunication between writers. But the vast
majority of responses supported the notion that documentation
developers belong in the software engineering organization.

The Rest of the Story
=====================

Management at Westinghouse Savannah River has not made a final
decision on whether to consolidate my team with the central tech pubs
organization. There's still a chance that the group will remain
located in the development organization. However, since this move was
proposed, the company has offered a voluntary separation incentive
that two of the three writers as well as the illustrator in the group
have accepted; the remaining writer is looking for another job before
the voluntary separation window closes at month's end.

One significant reason for opting out is that we are not comfortable
with the idea of being moved into a central tech pubs organization
from which we would be farmed out to whatever project is of
sufficiently high priority. As a result, we could be assigned to
document software, edit an environmental report, prepare internal
documents for release to the public, or whatever else might be needed.

The folks on my team object to the concept that technical
communicators these days are utility editors or renaissance writers.
Most of us are highly trained in a single technology which we have
often spent many years mastering.

At the end of April, I'll be facing new challenges as I start my own
consulting business. Thanks to everyone who responded to my request
for information. TECHWR-L and its members are an incredible resource!

--George Hayhoe
george -dot- hayhoe -at- srs -dot- gov till 4/28
GFHayhoe -at- aol -dot- com after 4/28


Previous by Author: Re: A Test to Select Competent technical Writers
Next by Author: Word 6 to Word 5.1
Previous by Thread: Re: slang
Next by Thread: chapter-based numbering


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


Sponsored Ads