Re: similar, yet different

["Ned Bedinger" <doc -at- edwordsmith -dot- com>]

----- Original Message ----- 
From: "Lisa Bronson" <lisa -dot- infocus -at- gmail -dot- com>
Subject: similar, yet different


> but given time contraints, my plan at this point is to document the
> base module and *only the differences* between it and the second
> module. And maybe that's the better way to do it, anyway?

I'm not clear on a couple of things:  I'm not sure that I see why one module
needs a full documentation treatment, and the other can get by with less.
And I am not sure that the preferred solution, given time, is to document
the core application twice--once for the mod1-only system, and again for the
mod1 + mod2 system.

The solution you propose could fit a system where the mod1+2 system simply
has more capacity for production, and mod2 is identical in most respects to
mod1.  But if, for example, the mod1+2 system is not just a simple multiple
(i.e., requires twice as many processors), but also requires a network and
middleware between them,  then I feel like your best shot at an efficient
document is to go for the full treatment of the mod1+2 system--you would be
noting where mod1+2 documentation is not applicable to a mod1 system.  The
good news is that you would simply change the focus from mod1 systems to
mod1+2 systems, without incurring additional scope, since your proposal
already includes the mod1 system and its differences with the mod1+2 system.

The driver behind my preference for a mod1+2 document is the possibility
that the mod1+2 system is more than just a multiple or extension of the mod1
system.  Mod1+2 might be exponentially different (as with the addition of
networks and middleware, in this example).  Mod1+2 might be the reference
implementation of the complete product concept, whereas the mod1 system is a
practical standalone subset of it.

In any case, your developers should be able to give you their analysis of
what is needed in the documentation, if you haven't been working with it
long enough to have that information already.  I imagine they know the
product very well, could give you their view of the customer's documentation
priorities, and would be on board with your concept (with or without the
shift in focus) if it is in line with the nature of mods1 & 2.

This leads to another consideration.  I think there's a lot riding on who
your users are.

If your target is end users or operators, and the mod1+2 adds enhancements
are mostly not visible to them, then your concept should fly nicely without
further adieu.  They usually don't need to know what's inside the black box
that produces their output.

If your target is an IT team, then I don't see any shortcuts available.  If
mod2 or mod1+2 has additional installation, configuration, support, and
maintenance requirements, then these are a primary consideration IMUO (in my
uninformed opinion) and not an appendix to mod1 systems.  Even if the two
module system has only one customer, that one IT team would need a document
that covers everything in their purview, whether visible or not.  I don't
mean that your proposed concept violates some rule of IT documentation, but
I think this consideration does lobby for the mod1+2 focus..

I have one more consideration for you.  I think your solution also depends
on the state of the product.

If this is a beta or a special limited distribution of your product, then
that might explain why you have such a limited time to complete the work
(the customer may already have a direct line to the development team and
already knows what is coming).  If this is the case, then you might be able
to put off consideration about the full documentation solution and focus on
meeting only the specific information needs for this release.

All things considered, it looks to me like your best option might be to:

1. Develop a concise table showing the differences.
    Diagram the complete system with a boundary around the core.
2. Create a piece that describes the simplest test for
    determining if the installed system has one or two modules.
3. Write the documentation with mod1+2 focus, and
     o  call out the parts that don't apply to some systems.
     o  cross reference those back to the test/concise table/diagram.

I don't like this solution much--I've seen similar documents that pushed the
boundary between documentation and high-pressure sales brochure--I think the
side-by-side comparisons has a natural tendency toward language that casts
the mod1 system as limited instead of capable.  I also think that my
proposed design tends to obstruct understanding and usability, because it
leads you to try and cover more than one product in each step or section,
but this is a problem that compounds as more products are added, and two
products might not be much worse than one.  If I had to make a management
design decision with these considerations in mind, and based on your
constraints, I would do it as described.

I know you won't have any problem flipping this advice (or blowing it off
entirely) if my concept of your mission or product is misguided.  Have fun.

All standard disclaimers, etc.

Ned Bedinger
Ed Wordsmith Technical Communications



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl

WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l 

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.