RE: Of myth and reality

["David Knopf" <david -at- knopf -dot- com>]

Dick Margulis [mailto:margulis -at- mail -dot- fiam -dot- net] and I seem to agree on
many of the facts but to draw slightly different conclusions from them: 

| "David Knopf" <david -at- knopf -dot- com> wrote:
| 
| >I think you make a good point in that a writer who is not willing or
not
| >able to keep these balls in the air is going to find it very
challenging
| >to write a true single source document.
| 
| <archly>The evidence would suggest that many people who make their
livings
| as tech writers may fall into this category.</archly>

There was a time when many tech writers found 'online Help' a strange,
new, and awkward medium. Many, if not all, of us made the transition
successfully. I think we are at the same point now with single source
documents. 


| On the other hand, I think you
| >significantly overestimate the difficulty of the task.
| 
| Not really. It isn't so much a question of difficult as it is one of
| degrees of freedom. A system with more degrees of freedom is
necessarily
| more complex than a system with fewer degrees of freedom. Complexity
| increases error rates and decreases productivity. I'm just taking the
| position that we can apply this simple engineering principle to the
design
| of single-sourcing solutions.

I agree that we can, but I disagree that a single source system offers
"more degrees of freedom." In fact, I think the opposite is true. A well
designed single source system imposes a certain amount of discipline on
the choices an author can make when it comes to structuring and tagging
content. In addition, because content for multiple output media (or
multiple audiences or multiple product variations) is created and
maintained in a single set of source documents (or a single repository),
error rates typically go down and productivity typically goes up. 

Don't misunderstand. I agree that it will take the typical writer
*longer* to produce a 1,000-page "single source document" than it would
take the same writer to produce a 1,000-page "user guide." There are
more decisions to make, and there is somewhat more complexity. I am
arguing, however, that producing the 1,000 page single-source document
will take significantly less time than producing the content for one
medium and then repurposing it for another using a different set of
tools, workflow, and so forth. This multi-source repurposing model is
inherently inefficient, error-prone, and costly. 


| I do this kind of
| >writing all the time, as do many dozens of writers I have worked with
in
| >the software industry over the last few years.
| >
| 
| Again, I don't see it as being _too_ difficult for a bright person to
| master. I question the necessity of asking anyone, bright or
otherwise, to
| master it.

Necessity is a strong word, but the benefits for some are so substantial
as to be impossible to ignore. If single sourcing enables a group to "do
more with less," improving quality and productivity while reducing
costs, it is difficult to ignore that solution. (I am not a proponent of
"single sourcing über alles" and do not mean to suggest that these
benefits will accrue to every project in every situation. Single
sourcing is right for some projects, wrong for others. But when it's
right, it's really really right.) 


| >Why? Conditional elements are routinely used to create
platform-specific
| >content, audience-specific content, *and* media-specific content.
These
| >are the purposes for which conditionals are intended.
| >
| 
| Yeah, fine. But what I'm arguing is that you shouldn't NEED to use
| conditionals for all three purposes. The medium-specific stuff should
be
| handled more automatically...(cont'd below)

And the good news is that much of it is using tools that are available
today. 


| >| If I am writing for the
| >| benefit of a system administrator, it doesn't matter to me whether
| >that
| >| system administrator is reading print or online text.
| >
| >Why not? There are things you would want to vary even for this
audience.
| >To take an obvious example, your print document might say: "For more
| >information, see 'Configuration' on page 3-36." In your online
version,
| >the "on page 3-36" portion should not be displayed.
| 
| The system should be smart enough to replace a page cross-reference
with a
| hyperlink and adjust the wording accordingly. I do need to create the
| cross-ref, but I shouldn't have to do anything else.

Of course. And a true single source system is smart enough to do just
that. But those who produce content for print and online and do so with
tools that do not support single sourcing often spend hours/days/weeks
touching up precisely these kinds of issues when they move content from
one medium to another. True single sourcing eliminates this redundant
and time-consuming effort. 


| Well they may be. Nonetheless, I'm arguing that one of the barriers to
| single-sourcing is the perceived complexity of the solution. Going
from
| three degrees of freedom to two simplifies the solution and may bring
more
| people into the fold.

Absolutely true. The *perceived* complexity is a barrier. I am arguing
that the perception is often different from the reality. Many technical
writers, as evidenced by posts to this list and others, perceive the
solution to be more complex than we have found it to be in actual
practice. 


| >A great deal of this can be automated. When it comes to the actual
| >writing of sentences, however, we rely on the author, but the
author's
| >task is not so great. For example, if the author writes a sentence
that
| >begins, "This manual describes," the author will have to remember
that
| >manual is generally a print-only term and include an appropriate
variant
| >for the online version. In this case the author writes, for example,
| >"This manual Help system describes" and applies a print-only tag to
the
| >word "manual" and a Help only tag to the phrase "Help system." It is
not
| >so difficult to get used to this kind of writing.
| >
| 
| I would prefer "This <volume/> describes" ...

And that would be fine with me. :-) I was merely pointing out that
varying the actual words and phrasing in a document is not difficult to
accomplish. 


| (In any case, when I look stuff up in PageMaker online Help--HTML--and
| then think, hmmm, I wonder if the printed manual has any more on this,
I
| find that it does not. The text is identical. So I think the solution
to
| the type of problem you pose is just better editing standards in the
first
| place. Eliminate unneeded self-references to the medium.)

In many cases, yes. But if an author considers a sentence beginning with
"This chapter" to be appropriate for the printed document she is
producing, she should not be prevented from writing it, nor should she
be bound later to edit it in some separate authoring tool to produce an
online version of the document. 


| It isn't that I don't think writers should have to keep the idea of
| tagging stuff in their heads while they are writing--and even remember
| that there _are_ multiple output media. It's that I don't think they
| should have to remember what all those media are and guess what
additional
| ones might be coming along.
| 
| I mean, what's the point of single-sourcing if your entire content
base
| becomes instantly obsolete when a new medium comes along? Then it's
not
| single-sourcing anymore. In your model, you've predetermined what the
| universe of possible media consists of before you start writing. 

Not really. We know, for example, that we will be producing printed
output, PDF, and HTML for an intranet web site. If it's later determined
that we must also produce HTML Help or JavaHelp, that is quite easy to
accommodate. Likewise if we discover the need to produce XML. <tongue in
cheek>Yes, I suppose if we were suddenly asked to produce a musical
version of the user guide, we'd be in a bit of trouble, but that doesn't
seem likely.</tongue in cheek> What sort of new medium did you have in
mind that might come along and break everything? 


| In my
| model, as long as I know that some term might be medium-sensitive and
tag
| it accordingly, I can move on.

That's all we do in the single source environment: identify the type of
information, tag it accordingly, and move on. 

Perhaps I am not understanding your model. How does your model take care
of the requirement to produce printed, web-based, and online Help
versions of the same 1,500 "pages" of content where the content in the
three deliverables has at least 90% overlap? 

Curiously,

David Knopf / Knopf Online / San Francisco, CA 
mailto:david -at- knopf -dot- com  /  http://www.knopf.com 

Consulting & Training on FrameMaker & WebWorks Publisher 
Consulting & Training on RoboHelp 
WebWorks Publisher Certified 
Member, JavaHelp 2.0 Expert Group 
Moderator, HATT & wwp-users




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