Re: Queries on Single Sourcing
Lyndsey,
You or someone else made this same point when I had a little rant about single-sourcing a short while ago. I agree that it is possible to create good online help using ss, but I don't see how you can use ss to create online help AND a user guide that each contain different information. The whole point of ss is surely to to reduce the time spent on doc by allowing the author to create multiple docs from a single source. As I see it, by definition, the content must be the same, and only the appearance different. And therein lies the problem: if the user cannot find the info in one source, s/he goes on a fool's errand looking for it in another.
When you last made your point about good help, I checked the archives, which informed me that ss'd docs are good only if they contain different info. Well, how? "Single-sourced" and "different" seem to me to be mutually exclusive terms.
Let me offer a scenario that may clarify the picture for you.
Suppose we're building an order entry system for Products 'R' Us. We need four documents: training student guide, training instructor guide, system reference manual, and online help.
The student training guide has a chapter on registering a new customer. It walks the student through three screens, with pictures. The instructor guide has a parallel chapter, but it includes additional notes for the instructor.
The system reference manual describes every screen in the system organized alphabetically by screen title, with pictures. It also has a section that lists every field name in the system and describes the format and content of that field as well as what it relates to in the database structure.
The help system is context sensitive.
Okay, what do we have to write? For each screen, we need to write a procedure for completing it. (Our audience is order entry clerks. No matter how brain-dead simple the screen is, we need a procedure that steps them through it.) We also need to write any technical notes about the page that a system administrator might need or that a trainer might want to be aware of. For each field, we need to write a description of the content and format. For each field, we also need to specify where it ends up or comes from in the database. And we have to take screen shots and render them in two formats--for print and online.
Now that we've written all those chunks, we're in a position to assemble our various outputs from them (with a good deal of automation one would hope), picking the category of information needed for the particular output document and organizing the chunks according to the plan for that document.
Well, maybe that saved us a fair amount of work--trading off the time spent planning and developing the single sourcing system against the time saved by avoiding duplicative work.
But wait, there's more.
QA tests our procedures and realizes that there is a gross logical error in the screen flow. Data needed on screen one isn't entered until screen two. That just won't do. So they send it back to development to be fixed.
Now we have two new screen shots and we have to revise a couple of procedures. We don't have to rewrite field descriptions, because the field moved but it did not change its meaning.
We plop these new graphics and revised text into the single source system, and voila, we have four revised documents coming out the other end, all in sync with the changes, all automatically.
Does that make more sense to you?
Follow-Ups:
- Re: Queries on Single Sourcing, lyndsey . amott
References:
RE: Queries on Single Sourcing: From: Bill Swallow
Re: Queries on Single Sourcing: From: lyndsey . amott
Previous by Author:
Re: Editing .pdfs - Continued
Next by Author:
Re: FONT STANDARDS
Previous by Thread:
Re: Queries on Single Sourcing
Next by Thread:
Re: Queries on Single Sourcing
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads