Re: Object-oriented specs to Human-oriented docs

[Graham Dowden <dowdeng -at- NMS -dot- OTC -dot- COM -dot- AU>]

> Ernie Tamminga <et -at- DSC -dot- COM> asks for Human-oriented help.

The first thing that came to mind was the statement attributed
to Marie Antoinette on being told "Your Majesty, the users have
no procedures to read", to which she replied "Let them read CASE".

Seriously, visual/diagrammatic methods are often the simplest to explain
complex systems, provided you understand the language. However, some
types of diagram describe internal structure/organisation and not
external appearance or function. Entity relationship diagrams (objects,
classes etc) are often in this category.

Other types of diagrams which may be more useful are:
* Data flow diagrams
* Procedural hierarchies
* Organisational diagrams
* State diagrams
* Architecture diagrams

A few suggestions and possibilities:

* Create or use additional relevant diagrams so that:
  - the writers can understand the product
  - the diagrams can be used in the final docs
  - SW developers can better understand the product (gasp!)

  > Our products are very complex, and involve myriad
  > customer-administrable, configurable elements

  It must therefore have possibly hierarchical relationships which
  can be described, and defined configuration procedures.

* Involve the writers in GUI/functionality design and review alongside
  the software developers. This way they are familiar "the latest"
  product and can help design it from a user perpective.

* Appoint one writer to get their head right around the whole product
  so they can clearly explain the big picture and what it is for.

* Prepare template procedures containing object classes, then
  import or copy the appropriate instance data when the GUI is complete.
  Your CASE and publishing tools will determine the difficult of importing.

  Example

  A. CASE information
  -------------------

  obj(DialogBox){ (class(StayPut), name(ConfigChannels),
   contains(
     obj(List) {class(DropDown), name(cfgFilter), values(cfgFilter)};
     obj(Dial) {class(Discrete), name(cfgBalance), values(1-10,1)};
     obj(ButtonGroup) {class(MustPress), name(cfgCommmit),
       values("OK", "Cancel")};
     );
   };

  B. Procedural document template
  -------------------------------

  The [name(ConfigChannels)] [obj(DialogBox)] enables you to configure
  [parameters]. [More info]

  To configure [parameters]:
  N  Select [option] from the [name] menu to display the
     [name(ConfigChannels)] [obj(DialogBox)].

     [graphic: name(ConfigChannels) obj(DialogBox)]

  N  Select a value for the [description] from the [name(cfgFilter)]
     [class(DropDown)] [obj(List)] to define [description].

  N  Select a value for the [description] from the [name(cfgBalance)]
     [(obj(Dial)]. The values are [values(1 to 10 step 1)].

  N  Select the OK to commit and close the [name(ConfigChannels)]
     [obj(DialogBox)], or the Cancel button to cancel.

  C. Procedural document
  ----------------------

  The Configure Channels dialog box enables you to configure
  pre-amplifier channel settings. Etc.

  To configure pre-amplifier channel settings:
  1  Select Pre-Amp from the Config Channel menu to display the
     Configure Channels dialog box.

     [graphic: Configure Channels dialog box]

  2  Select a value for the Hi/Lo pass filter from the
     Filter drop down list to define the filter applying to the channel.
  ...

Bottom line: Use and augment OO methods, integrating documentation with
software.

Regards,
--
Graham, dowdeng -at- nms -dot- otc -dot- com -dot- au

 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