Summary Report: Justifying a Separate Existence

[George Hayhoe <george -dot- hayhoe -at- SRS -dot- GOV>]

     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