RE: When Worlds Collide: McConnell meets H

["walden miller" <wmiller -at- vidiom -dot- com>]

I just want to weigh in with my experience in spec writing in small and
large corporations.

My docs department at OptImage/Philips (five years ago) wrote all technical
specs for all software products.  We were included in all design team
meetings and had the following tasks:

1. keep minutes
2. write/update specs
3. act as a software designer (active member of the team)

We went about writing specs the same way we went about writing user guides
or tech reference manuals: get input from engineers and address our audience
appropriately.  The nice thing was that our audience was wider than a user
guide: it included marketing, engineering, release, training, and
documentation.  This allowed us to include procedures and GUI definitions
that you rarely see in specs.  But it did allow us to get a jump start on
the final manuals.

In my current position, no writers are part of the design team. The docs
department has attempted to influence the specifications by proposing
formats and outlines to include appropriate information.  This has increased
the usability of the specs, but the real issue has been updating the specs.
Engineering-owned specs (unless kept in line by very good project/product
managers) rarely get updated once development begins.  This is an issue we
confront daily.

Both McConnell and Hackos are right to the extent that they genericize
process.  In my experience, process in always local and cultural. Writers
are activists in the processes (product, writing, engineering, etc.) that
they are involved in.

My advice is for writers to insinuate themselves in design teams/decisions
even if it means more work.  In the long run it pays off.

walden miller
director
vidiom systems
boulder, colorado