Re: Single Sourcing

["Tim Altom" <taltom -at- simplywritten -dot- com>]

Let's back up a few yards here and take a look at some basics first.

When we ask "should I do this or that?", we often have an unspoken
assumption that we know each other's priorities. Quite often, we don't, and
many of the disagreements you see on this list result from that mismatch. In
this case, we're not together on one of your primary priorities: which do
you need more, usability, or maintainability? They're in conflict here.

Users don't like to flip. They like steps repeated where they need to be. So
most users benefit from repeating the steps for opening a preliminary
window. Yet, that makes maintenance extremely hard. If you now change the
steps for opening that window, you may have to find them in dozens of
topics.

On the other hand, if you cluster all tasks independently, including how to
open that one window, maintenance is a snap. When the steps change, you
change them once. Everything else is a cross-reference ("For more
information on how to open the window, see..."

In general, we advocate that departments opt for maintainability first, so
long as it doesn't cause any discernible problems for users during testing.
Don't let users just TELL you what they want all the time...that's often
misleading, because users may tell you they want all sorts of things, then
not use them. They're like kids that way. Usability is often a problem in
tech doc departments, but the major problem we see in many departments is
that their documents are so scattered and difficult to update that when
updates are needed, they're often deferred to a later date. That ultimately
robs users of information they need, in the name of keeping a marginally
useful feature alive. Most tech doc departments aren't very efficient, and
it eventually results in frustration, missed deadlines, turnover, lack of
training time, and so forth. That's why we use Clustar so much: it provides
a balance between usability and efficiency, with the flexibility to shift
slightly to increase either one.

Clustering information more completely also helps you single source, because
when you break the clusters apart (say, in a database), it's extremely
efficient to be able to pull one out for update, change it, and put it back.
That discipline is vitally important in a single source environment. When
you have ongoing projects always gobbling up your time, maintenance
shouldn't be so huge an issue that it never gets properly done.

Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar(TM) System
"Better communication is a service to mankind."
317.562.9298
Check our Web site for the upcoming Clustar class info
http://www.simplywritten.com

----- Original Message -----
From: Melanie Shook <mshook -at- com2001 -dot- com>
To: 'Tim Altom' <taltom -at- simplywritten -dot- com>; TECHWR-L
<techwr-l -at- lists -dot- raycomm -dot- com>
Sent: Friday, March 31, 2000 5:36 PM
Subject: RE: Single Sourcing


> Tim Altom wrote:
> <Ah, yes...we do this all the time. Check out our website for some
examples
> and hints: www.simplywritten.com.>
>
> Thanks Tim.
>
> I guess to be more specific, I may have an instruction that says:
>
> 1. Open the Whatzigig page.
> 2. Select the Thingamagig option.
> 3. Click "OK." You will be returned to the Dealywhopper page.
>
> In the printed matter, I've explained how to open the Whatzigig page (e.g.
> Right-click on the Toolbar, Select Dealywhoppers>Whatzigig).  Then there
are
> several options from the Whatzigig page, each of which is a different
> Heading2, and a different topic in HTML Help. In print, it doesn't make
> sense to repeat how to open the Whatzigig page 10 times. Or does it?
>
> So my question is, in the online version, should I repeat the instructions
> for opening the Whatzigig page in each topic? Should I include a link to
> those instructions in each topic? Should I NOT assume the reader can't
> figure this out? What is the BEST way when I'm single sourcing?
>
> Some of this could be answered through usability testing, and I'm trying
to
> get approval for this, but we just added a QA department that only has one
> person, and I'm the whole tech pubs department, so there's not a lot of
> personnel to get this done right now - later on down the line when we've
> hired everyone it will hopefully be better.
>
> It seems to me from reading the Simply Written website that you are
> advocating repeating the instruction each time, so that each modular topic
> is complete in itself. Anyone else have an opinion?
>