RE: Of myth and reality

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

"David Knopf" <david -at- knopf -dot- com> wrote:

[much snipped to avoid the Wrath of Bot]

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

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

>I think the key point is how much overlap is there or, put another way,
>how much variation is required to accommodate the various output media.
>To use an extreme example, for a document in which every paragraph must
>have different content for print and online, the single source approach
>to writing would be overwhelmingly complex (and would offer little
>pay-back anyway). For most documents that we work with (mostly software
>documentation and online Help of various forms), the overlap is greater
>than 80% and usually greater than 90% in terms of actual written
>content. 
>
>While there is always some adjustment when a writer begins creating
>single source documents, it is not usually overwhelming. In fact, with
>80-90% overlapping content, it's pretty straightforward.
>

Not arguing with that. [By the way, I'm mostly inserting these comments to break up the continuous quoted matter for Lyris's benefit. You can ignore a lot of them ;-)]


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


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


 
>
>
>| It does matter
>| that I may need to expose certain details to the administrator that
>I'll
>| hide for the user.
>| 
>| So in some sense using conditional elements is a form of
>single-sourcing
>| (one source, multiple audiences).
>


>Certainly. Single sourcing enables you to tailor content for a
>particular product variant, a particular audience, or a particular
>output medium. These are the three classic applications for single
>sourcing. 
>

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.


>
>| However, I think of single-sourcing more in terms of one text,
>multiple
>| media. And for this purpose, asking the author to handle the variants
>| while writing seems inefficient. It makes much more sense to build the
>| intelligence into the authoring _system_ rather than the authoring
>| _person_.
>


>Yes. We build as much of this intelligence as possible into the
>authoring system itself. For example, if we determine that screenshots
>within procedure steps will be included in print but excluded from
>online Help, we automate that (though tagging) so that the author need
>do nothing extra in preparing the documents. 
>
>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" ...

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

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


[remainder snipped]

Cordially,

Dick


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