Re: applying OO

[mpriestley -at- VNET -dot- IBM -dot- COM]

Bonni Graham (in an interesting and informative post) said:
>First off, it can be very helpful to the users to frame/structure the
>document in the same way the program is framed/structured.  So if you're
>documenting an OO program, you'd want to try to use that paradigm.

I don't think this is a good rule to follow (at least not blindly!).  I
have written documentation for a sprawling (70+ windows) application,
which was written in OO C++.  Many of the windows were re-used in multiple
contexts, with minimal changes.  Most of them had to have separate helps
written for them, because they appeared in different "flows" for the user:
the window was being used for different things, and appeared in different
contexts.  This was something we had to keep an eye on, because programmers
were liable to add a new window, and tag it in their minds as "minimal effort"
thanks to OO, and then lobby for it to be included.  I'd get a look at the
proposed design change, blanch, and whisper: "a new window? three new buttons?
a new task help? within our existing schedule?" sure I could re-use the help
for the Cancel button, but...  and then I'd start gnawing on the table edge and
frothing at the mouth until they carted me off.

So, a couple of caveats to Bonni's point:
1) help for the interface includes the context and "flow" within which a
window or button is used.  This can change the help entirely, even when the
window looks identical.
2) The user interface in general could have very little to do with the
internal structure of the program.  There is no reason why the user should
either know or care about these internal workings (unless they're planning
on fixing the bugs!)

Thanks,

Michael Priestley
mpriestley -at- vnet -dot- ibm -dot- com
Disclaimer: my opinions not IBM's.