Reality not myth (long and opinionated)

[Doc <dlettvin -at- attbi -dot- com>]

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.

Have you ever wondered why the cost of localization is so high?
Have you ever wondered why their is such a long lag between the ENU
release and the FRA and DEU?

Now you know. 

This is why most L10n firms will *not* start documentation until after
it has been released.

Okay, it's 6am, my daughter just brought me a cup of coffee to keep my
brain cells alert until the espresso bar opens. I have been writing
since 4 and it is time to take a break.

<turning the rant valves to the closed position>

-Doc
David W Lettvin
VerText
South Hamilton, MA
978-468-1105

When you're average, you're just as close to the bottom as you are the
top. 
Alfred North Whitehead 

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

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