Re: Of myth and reality

[Dick Margulis <margulis -at- fiam -dot- net>]

David Knopf wrote:

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



DM:
Yes, that's fair. We agree much more than we disagree.


DK:
>
> | On the other hand, I think you
> | >significantly overestimate the difficulty of the task.
> |


DM:


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


DK:


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


DM:

Yes. There is no question that a single-source system offers fewer
degrees of freedom than exists where everything is written and
maintained independently (and often ad hoc). My point was that the model
for single-sourcing can be improved to lower the number further.

DK:


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


DM:


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


DK:


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


DM:

No disagreement there.

DK:


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


DM:


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


DK:


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


Good. That's different from what you said earlier, though.


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


DK:


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


DM:


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


DK:


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


DM:

And we agree yet again!

DM:


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


DK:


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


DM:

Again, we're both on the same side in saying that single-sourcing is a
good thing. I'm just trying to refine the model.


DK:


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


DM:


> | I would prefer "This <volume/> describes" ...
>


DK:


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


DM:


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


DK:


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


DM:

Well, this is straying far off our chosen topic, but I don't think it
should be the author's choice in a structured environment like the one
we're discussing. She bloody well should be prevented from writing
it--but by house editing standards, not by the tool.


DM:

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


DK:


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


DM:

Whatever the PHB decides. Whatever Bill Gates decides to market.
Whatever the file format of Word 2005 turns out to be. Cell phones.
Outlook RTF. Quark. Quicksilver. How should I know? All I know is that
the minute I say, "Hey, we've got a single-source system; it let's us
write once and output to PageMaker, FrameMaker, PDF, HTML, and ASCII,"
IT is going to inform me that we're switching to Lotus for email and the
marketing vp is going to tell me that we're about to outsource all our
documentation starting next week and the vendor wants all our material
as Excel files.

DM:


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


DK:


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


DM:

In my model, the true "content," that is, the facts, ideas, and
sentences, should have 100% overlap. The medium-specific differences
should be handled entirely (okay, almost entirely--nothing is perfect)
by the system. Is the material organized differently? Fine. Do
cross-refs look different? Fine. Does the same procedure change from
third person in a design spec to second person in a Help file? Fine. I
know I'm shooting high here, but I can dream, can't I?


Dick





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