Object-oriented specs to Human-oriented docs

["Tamminga, Ernie" <et -at- DSC -dot- COM>]

Our erstwhile Technical Publications group (now named Information
Engineering instead, to my own credit/blame) is undergoing a major
paradigm shift in how we gather the information we need for producing
customer-useful documentation of our company's software products.
(Our products are very complex, and involve myriad
customer-administrable, configurable elements in addition to end-user
feature-functionality.)
    I'd be most interested in hearing from folks who have gone through
(or present progressive...) the experience of taking Object-Oriented
engineering diagrams and "specifications" and generating, from them,
documentation that explains clearly the CUSTOMER FUNCTIONALITY of the
proposed products.
   If you're still interested in staying with me on this topic, herewith
are some more detailed observations...
=======================
In days gone by, a couple of species of "technical specifications"
documents produced by the software engineering staff addressed topics
that were directly pertinent to how the customer would eventually
experience, use and administer the product. This gave my Doc group the
ability to begin writing manuals at the same time the software
developers began writing code.
However, as software development tools have grown increasingly
sophisticated, a couple of specific changes are directly and
significantly having an impact on the Doc work:
***BIG ITEM NUMBER ONE: The Object-Oriented approach to analyzing,
designing and developing software has allowed software engineers more
tersely and effectively to "capture" the real-world shape of the
situations and objects they're modeling. A whole language and notation
of O-O analysis has allowed them to create, in diagram form, abstract
but powerful representations of proposed software systems. These
diagrams are REALLY SWELL for software engineers to work from. But by
and large these diagrams now take the place of what used to be more
descriptive, written specifications -- which used to contain at least
strong "hints" of the ways the CUSTOMER would eventually experience the
product.
   The folks in my Docgroup have gone through Object-Oriented Analysis
training and can read these diagrams fairly well -- but there's a large
gap between this view of the world and the view that will be presented
to customers in their experience of the product.   The product is
presented quite nicely in the diagrams in terms of objects, classes,
attributes, methods, etc.     But the CUSTOMER is not going to
experience the product in those terms.

***BIG ITEM NUMBER TWO: Powerful modern software development tools allow
programmers to create Graphical User Interfaces practically "on the
fly". Creating a user-interface used to be a much more complex software
development task, and the interface design was VERY difficult to change
late in the game. And so the proposed interfaces were carefully worked
out early in the product development process. The "old" result was,
again, that my group could productively work on the manuals while the SW
engineers worked on their code.
   Now, however, user interfaces can be designed very late in the game
(and in fact there are even very good arguments for DOING that -- which
I won't go into at this moment). During the EARLY phases of product
development, this makes the job of documenting the user/administrator
view of the product rather abstract, since the exact procedures and
interfaces that will be used by the user/administrator are not nailed
down in detail.
...and the LATE phases of product development would be too late for
beginning the documentation work.

***OUR GROPING TOWARD AN APPROACH: Our approach to designing the
documentation for the new product line is to focus on identifying each
and every PROCEDURE that the user/administrator is going to have to
know. These are nowhere spelled out in the engineer-oriented technical
specifications documents; rather, they are magically pulled out via the
analytical skills of the doc-folks after very close (and multiple)
readings of the techSpecs.

After a whole pile of required procedures has been identified, we
determine which medium/media will be most pertinent for each procedure.
(For example, documentation of procedures for installing our product for
the first time will have to be made available on paper or on CD-ROM --
not in the form of online help -- since online help itself won't have
been installed at that point in the customer's experience.)

Then we have to look again at the techSpecs to winnow out all
information we can that is pertinent to our target procedures, and
then... then, what?  We're anticipating having to do a lot on ongoing
software-engineer-interviewing to fill out our understanding of the
functionality, and the underlying/overarching administration-tasks, of
the new product line. And so far, all the SW-Engineering teams have
promised full cooperation.     But we all know how challenging it is to
get real "quality time" with software engineers once the development
effort enters its true crunch phase.

I could go on and on at much length, but I'll stop for now, and request
that if any of youse folks find/have-found yourselves in similar
predicaments, respond to me, & maybe we can help each other build (you
should pardon the expression) a bridge to the [documentation] future.
Regards--
  Ernie Tamminga
  Director, Information Engineering
  Digital Sound Corporation

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html