Documentation for Component Software?

Subject: Documentation for Component Software?
From: Todd Snarr <todd_snarr -at- AUTOSOFT -dot- COM>
Date: Fri, 9 Jan 1998 09:59:59 -0700

Hi,

Anyone out there experienced in developing documentation for component software--software consisting of "distributed objects" that can be plugged in anywhere on a network? We're developing a distributed, object-oriented system that consists of several subsystems and plug-and-play components. The product provides a core subsystem (which consists of several key components) that all customers can purchase. Beyond that, the product offers additional subsystems and components that customers can purchase as well. Most often, they'll be purchasing many of these additional components. If they don't have a need for additional components, because they already have similar systems in place, they can even integrate their current systems in with our core component (and take advantage of all the services that the core provides).

Intitially, I performed a task analysis for operators, administrators, and developers and plannned for three different guides, one for each audience. The challenge? Many tasks and user activities cross component boundaries. If a customer purchases the core and all but two subsystems, I'll have to delete references and all information in all three guides about the subsystems and components they didn't purchase. This can get messy...particularly with online Help.

So far, management here wants an information solution that provides only what the customer purchased. This makes sense...cut down on the size of the deliverables provided. But with a task-oriented design, it's either deleting info about components not purchased (all over the guides) or structuring the information (I hate to say this) around the system. Possibly, with this second approach, we could provide one guide, organized alphabetically by topic (or component), and then have all relevant tasks under that topic. This way, I could at least customize one guide as opposed to three or four, adding those topics (components) the customer buys or pulling out information about topics not purchased. In this case, "plug and play" would not only hold true for the system, but for the documentation as well.

"Plug-and-play" has its advantages in the software industry, but so far I haven't seen any for the information developers. Has anyone developed custom documentation similar to this before? Any suggestions? Successes? Failures?

Todd Snarr
Auto-Soft Corporation
todd_snarr -at- autosoft -dot- com




Previous by Author: Re: MS Manual of Style
Next by Author: Re: Word 7 Query: Auto update of fields in Headers?
Previous by Thread: a hearty thank you
Next by Thread: Re: Documentation for Component Software


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


Sponsored Ads