TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
"How DO you apply OO to documentation? Why would
you WANT to apply OO to documentation?"
How you do it I'll answer in the paper I post. To all of you firing off
SASE's -- I'll send the formatted paper (for your reference) and the
handouts, which illustrate the concepts I describe in the paper.
Why you would want to is touched on, but not really explored thoroughly in
the paper, so I'll go into a little but about why *I* applied it. My
solutions may not be right for everybody.
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.
One of the programs I was documenting was a development environment. The
audience was primarily COBOL and other structured-language programmers who
suddenly had to switch (because of upper management's decision to use OO
technology) programming paradigms. OO is VERY different conceptually than
structured programming. We had to bring people up to speed quickly, and one
of the ways we did it was to incorporate OO concepts directly into the way we
built the books and online help (especially online help). In a sense, the
book set modeled the new concepts -- provided a visual/functional example of
the shift in thinking the readers would have to make.
Secondly, it can cut down on your work a lot -- especially in online help.
Use encapsulation -- write the help down to the screen element level, rather
that the whole screen. Suddenly, you only have to write the help for, say,
the OK button once -- and if it changes, you only have to change it in one
place. If you have a lot of topics, this can help. (You'll also want to
include a topic that summarizes the screen, of course.)
Use inheritance. If you have a topic describing how to create a query and a
topic describing how to put a query's results into a data analysis model,
make step one of the second topic: "Create a query" (picture that phrase as a
hyperlink). Then you're inheriting the description of how to create a query.
Many/most of us may already do this, but believe me, I've seen LOTS of help
systems that don't.
Use the method/message concept to remind yourself that you're writing to
answer user questions. Their use of the manual and online helps to mirror
this concept. At least mentally, they're sending a "message" to the
book/help screen: How do I do this? What is it? How do I use it? Why did
it do THAT?, etc. The book or help screen needs to be able to respond to
that message. If you keep that in mind, you can use the method of explicit
text or graphics as a returning message.
Applying OO can help you AND it can help the reader. As I say in my paper
(which you'll see soon, hopefully), "You may already be doing these things."
In many ways, they're already tenets of good writing. But OO gives us a
framework for applying these things that the programmers can now also
understand -- because they're having to do the same thing. You now have
terminology and language that you can use to explain why you need certain
pieces of information or whatever. In structured programming (at least in my
experience with it), the analogy by which you could put writing into
"programmer terms" (so they could understand what you do well enough to buy
into supporting your doing it well) was much more tortured.
I like OO. I think it's where programming is going, and I think it should
be. It's much much closer to the real world.
BonniG -at- aol -dot- com