RE: product dependencies... urgent!

Subject: RE: product dependencies... urgent!
From: "Ben Kovitz" <bkovitz -at- nethere -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 3 Jul 2002 08:22:13 -0700


Poorni Aravindan Kumar wrote:

> In the Product B's Release Notes, I've a note quoting:
>
> "Product B's software and product dependencies are specific to the
> Product A patch it supports (is bundled with). Its hardware,
> software, and product requirements are dependent on the Product A
> requirements.
>
> For information on Product A's hardware and software requirements,
> see Product A's Release Notes."
>
> Does the above note convey the required information?

Hi, Poorni. Here are a few thoughts.

Perhaps consider rewording in terms of explicitly stated
conditions that must be true in order for the user to do
explicitly stated actions. Some possibilities:

"To install product B, you must first have installed the following
software..."

"To install product B, you must have installed all the hardware
needed to install product A (see document ...) plus ..."

This approach replaces the words "are", "dependencies", and
"requirements" with the more-concrete verb "install" and an
explicit statement of what the user needs to check or do before
installing. "Install" might not be what you need to say, but I
hope it illustrates the technique.

Steven Brown suggested (in addition to first suggesting replacing
the word "dependencies"):

> I have a feeling that presenting the information in a table will
> help.

Yes! A table might make things very clear. And here is a neat
principle at work: the table can contain helpful redundancy
without wasting the reader's time.

For example:

Installation requirements

To install To install
product A, you product B, you
need: need:

Hardware X Hardware X

Hardware Y Hardware Y

Hardware Z

Software 1 Software 1

Software 2 Software 2

Software 3 Software 3

Software 4


Again, the facts here might not be right. But it's interesting to
see what happens when the document just spells out product A's
requirements alongside product B's requirements. The reader
instantly sees for himself that product B needs everything that
product A needs and a little more.

Here's an even simpler possibility: instead of mentioning product
A at all, just spell out product B's requirements in full. That
might make the job easier for the reader than making him find the
product A release notes.

--
Ben Kovitz
Author, Practical Software Requirements: A Manual of Content & Style
http://www.amazon.com/exec/obidos/ASIN/1884777597
http://www.manning.com/Kovitz


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
Save $600: Create great-looking Help files and software demos with
RoboHelp Deluxe. Get RoboHelp and RoboDemo - our new demo software - for one
low price. OR Save $100 on RoboHelp Office in June with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.



References:
Re: product dependencies... urgent!: From: Steven Brown

Previous by Author: The U.S. federal tax instructions
Next by Author: Astoundingly good technical writing: Who Is Fourier?
Previous by Thread: Re: product dependencies... urgent!
Next by Thread: Product dependencies... urgent!


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


Sponsored Ads