RE: Reality not myth (long and opinionated)

["Giordano, Connie" <Connie -dot- Giordano -at- FMR -dot- COM>]

Doc,

Thanks for the enlightenment.  I have been troubled by the whole
single-sourcing debate for awhile, because I couldn't figure out what I was
missing.  Now I know I'm not really missing anything, except maybe the tools
to make the process more efficient.  I already write all the training, all
the on-line help, all the docs, and 95% of the marketing, and I don't
rewrite most of it.  I say most, because there are some differences in
approaching an audience for one purpose over another, which usually means
style and voice change somewhat.

Our jobs, the programmers jobs, the QA's jobs etc can really be boiled down
to one simple rule.  If it doesn't help the users do their jobs more
effectively, then it's extraneous and unnecessary.

I'm not necessarily surprised by the number of folks who start with a manual
and rework for on-line...I did that myself until about four years ago.  In
fact, if you understand how to organize the information, it becomes easier
to write "help" topics first, then create a manual. Of course I'm a big
believer in being a generalist, so it didn't take me as long as it might
otherwise to come to this conclusion.

Now if I could only figure out how to put all this stuff in a database and
generate it on-the-fly.  Wait, that's a tools question....

Regards

Connie P. Giordano
Senior Technical Writer
Advisor Technology Services
A Fidelity Investments Company
704-330-2069 (w)
704-330-2350 (f)
704-957-8450 (c)
connie -dot- giordano -at- fmr -dot- com <mailto:connie -dot- giordano -at- fmr -dot- com> 
 
"I am always doing that which I can not do, in order that I may learn how to
do it." - Pablo Picasso 


-----Original Message-----
From: Doc [mailto:dlettvin -at- attbi -dot- com]
Sent: Wednesday, July 24, 2002 6:08 AM
To: TECHWR-L
Subject: Reality not myth (long and opinionated)



Okay look ...

I have been doing single-source effectively for more than five years.

It has nothing to do with bytes. It has nothing to do with
repurposing. It has nothing to do with anything other than a form of
disciplined writing.

The tools you use, the number of docs you want to drive are
unimportant.

Single-source is a discipline in which you minimize the effect of
product changes and maximize the usability of your content by writing
in small discrete modules that you can manage in some way.

The problem with most single-source materials is that, like FrameMaker
help, the help is distilled from the manual. manuals tend to be
verbose celebrations of the programmer and designer's ego rather than
a direct response to the user's needs. 

I believe in terse, brutal technical writing. 

When someone says, "Help text and manual text are different," my
question is why?

The interface is the same.
The user's needs are the same.
The task is the same.

These also reflect a prevalent myth in technical writing (as usual all
parties present are excepted) that the user's primary job is to
understand how the software works. This is balderdash. The user's job
is to use our products to do the work they were hired to do. They were
not hired to become software experts. If that were the case, we'd all
be fighting over ex-FrameMaker programmers for our technical writing
staffs.

Look at how many of the questions on this list are about software
problems. Indeed, many of the questions are even answered in the
software documentation. Why don't people search for the answers?

Because it takes too much time.
Because they're on deadline.
Because THEY ARE TRYING TO GET BACK TO WORK!

(Oh good grief, I sound more like St. Andrew with every post.)

Okay, I admit that I am hyperbolizing a bit, and I will probably
alienate some people.

There was some talk on the list recently about "fog filters". I have
developed my own internal filter. When I edit a document for content,
the question I continuously ask is, "how does this help the user?"

How many of you still believe that users read a manual linearly from
beginning to end? I don't. I've watched users and talked to users for
years. 

The user installs the software.
They work until they cannot figure out the next step.
They go to the manual or the help file. 

With a well-built, context-sensitive help file, one or two clicks are
all it takes for them to get the information they need to get on with
their jobs.

With a well-built, well-indexed manual, they go to the index where
clues guide them to the proper place to get the information they need
to get on with their jobs.

Other than the medium, what's the difference in the way people use
these documents? 

There is content which belongs in the manual rather than on line.
Installation, configuration, and other sequences that the user will
once or infrequently and may require that the program be turned off
are examples of uniquely manual content.

But for the bulk of the material, I contend that good content is good
content. And my definition of good content is that which lets the user
get back to the task at hand with the minimum possible delay.

That is my primary editorial criterion.

Yes, help is different from the manual. It's better! It's focussed on
the task. Help is designed with the understanding that the user
doesn't want to go searching for the answer.

And the curious thing is that the discipline of writing good help
content is the same as ... wait for it ... the discipline of
single-sourcing.

The method that my group used to successfully single-source was to
work from the specific to the general. In other words, we wrote what
looked like help content first. Additional explanatory materials were
judged on their relevance to the user's needs. If the information did
not add to the user's ability to complete the task then a case for its
inclusion had to be made.

Single-source is about content. Discussions of binaries, specific
tools, etc. are peripheral. You can write single-source material as a
linear document, or as a series of individual documents, but the
discipline is the same. 

We never did a formal ROI. We didn't have a budget to justify. But I
can give you some estimates and scenarios.

90 % of the help content appeared in the manual.
50-70% of the manual content appeared in the help.

With each revision of the software approximately 20% of the GUI was
rearranged without any functional change. Our methods minimized the
time spent revising the manual to accommodate these changes.

Reference documentation was built the same way.

About 40% of a given Sales and Marketing white paper was our material.

There is a significant problem with single-sourcing. It is a political
hot potato. Executives will love it if you can get the idea to them
because it means that you can do more with less. But as you start
proposing these ideas you will make enemies. 

Single-sourcing threatens jobs.

It is in the interest of every specialist to sell the idea that their
discipline is special. The unique characteristics of their information
product require that they, and only they, rewrite and rework the
material. It is hard to fault them for trying to protect their patch
of the company. 

But the point of single-sourcing is efficiency.

Let's take a look at it from a business perspective.

We'll imagine a business with one technical writer specializing in
paper documentation, one TW who is a help specialist, one marketing
writer and one training writer. I could make a case for technical
support too.

The print writer writes a paragraph.
The help writer rewrites it.
The marketing writer rewrites it again.
The training writer rewrites it once more.

Then a programmer decides that the documented widget needs to be
changed, and it starts all over again. 

If the writers are not communicating diligently (that couldn't happen
could it?), it is possible that you will end up with asynchronous
content.

This is a sad state of affairs, but it gets worse and more poignantly
ridiculous when you add one more factor.

If you are writing materials that will be localized, you now have four
separate paragraphs to translate. And each iteration of changes made
by the programmers requires four changes by the localization team.
[snip]




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Buy RoboHelp Deluxe starting at only $798: you'll get RoboDemo, the hot new
software demonstration tool that's taking the Help authoring world by storm,
together with RoboHelp Office. Learn more at http://www.ehelp.com/techwr-l

  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.

---
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.