Re: Object-oriented specs to Human-oriented docs

Subject: Re: Object-oriented specs to Human-oriented docs
From: Graham Dowden <dowdeng -at- NMS -dot- OTC -dot- COM -dot- AU>
Date: Fri, 11 Apr 1997 18:00:06 +1000

> 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


Previous by Author: Seeking Tech. Writer...
Next by Author: Re: Microsoft Manual of Style
Previous by Thread: Object-oriented specs to Human-oriented docs
Next by Thread: Re: Object-oriented specs to Human-oriented docs


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

Sponsored Ads


Sponsored Ads