TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
It looks like we're going to go through several drinks when we finally
meet Sean. (BTW I don't drink beer but single-malts definitely get my
attention.)
Rather than rehashing I'll annotate your excellent post. There are
multiple snips below.
>1) That printed documents are organized in a linear way and also
>are often used in a linear way, even though, indexes, TOCs,
>cross-references, thumbing through, and hypertext and bookmarks
>in online books might be examples of non-linear use (and following
>a thread of hypertext in a non-linear help file might be deemed
>. . . linear).
I would go one step further. I would contend that only certain
portions of any manual are used linearly. Anecdotally I can count the
number of users I have met who read a manual from beginning to end
linearly on the thumbs of one hand. That one user had an eidetic
memory which he used to store the manuals.
>2) That single sourcing can be used for more than just creating
>online help and a printed document from the same source, that it
>can be used to output a variety of deliverables from a single
>set of source files.
For example:
Knowledge bases
Training manuals
Electronic manuals
White papers
OEM specific manuals
To say nothing of its use in content management and the reduction of
redevelopment and translation efforts.
>3) That single sourcing is not always appropriate.
It's harder to come up with examples for this, but:
Products with only one doc medium.
Products with so little documentation that it's not worth the effort
Static products (no longer being developed)
Products intended for the use of 3 people in Tierra del Fuego
Okay, maybe that last snipe was uncalled for.
I will say this ... vehemently ... that even if you don't feel you
need to single source, applying the content discipline for
single-sourcing is appropriate. I'll rant more about this further down
the message.
>1) Single-sourcing does not begin with printed output. Single-sourcing
>begins with a successful design that considers all of its deliverables,
>often including both printed output and online help. A process called
>repurposing might begin with printed output, but that is not
>single-sourcing.
>For example, after you create your content in your single-sourcing
>framework, you decide what to output. You might choose to output online
>help first--or output both simultaneously (if your hardware supports it).
>There are two popular approaches to single-sourcing currently being
>used: database and super-set document. The latter, exemplified by
>FrameMaker and WebWorks Publisher Professional, requires the creation
>of a document that holds all the content, and you parse-out content as
>needed and by design to the deliverable (deliverable being online help,
>online PDF, PostScript for press, etc.). Both methods let you control
>content, as well as chunking, look, feel, and navigation.
>2) In what way does organizing online help in a linear way affect the
>use of online help? I submit, it is common to organize even traditional,
>multi-sourced (non-single-sourced) online help in a linear way, for
>ease of authoring, editing, updating, organization, and sanity.
There is also the issue of linearity for the user in help. Help
systems provide a Table of Contents. Are the definitions, processes
and procedures listed in that TOC totally different from the printed
documentation? If so ... why? If the help reflects the information
that people need at a certain point, the manual should do the same and
vice versa.
I've heard rationalizations about the depth of information provided in
the manual as opposed to the quick fix of help files. But if that's
the case it should be a matter of including and excluding blocks of
information rather than rewriting the entire thing.
One writer I talked to about this told me that there was a different
style to web and help writing. that it had to be read quickly and in
small chunks so the user could implement the action immediately. I
looked at him and said, "...your point being?"
>3) Online help is not PDF, though I agree it can be.
If you want to add another requirement to your product's box, "Adobe
Acrobat Reader required to access online help."
>4) Single-sourcing via a super-set document or database can be poorly
>done, just as multi-source, traditional RoboHelp-esque online help can
>be poorly done. And, both types of workflow suffer for many of the same
>reasons: a lack of time, lack of staff, and lack of funds.
There's another reason that it can be done poorly. When you develop in
a large document format, it is very easy to slip out of chunk and into
narrative mode. Writers who effectively single-source from the
super-set are extraordinarily well-disciplined.
>Like successful multi-source online help, single-sourced online help
>can succeed.
... and does! My group did it for five years.
>Single-sourced online help can be context sensitive, use pop-ups, etc.,
>and be functionally the same as multi-sourced online help. As with
>multi-sourced online help, single-sourced online help is as good as you
>choose to make it. Single-source templates reflect the time, effort,
>and skill you put into them. And, single-sourcing workflows can have a
>supreme advantage when it comes to resources: for repeated projects and
>projects that share content, single-sourced online help will save you
>time, staff, and money, while delivering at least the same quality as
>your multi-sourced project.
I've extolled my staff and their ability to deliver quality docs on,
or ahead of, schedule elsewhere. Single-sourcing is how we did it.
>In fact, I'd say a single-sourced online help project offers a chance
>at better quality, because your authors can focus on content instead
>of fretting the formatting, and, since only one set of source files
>are maintained, you don't have to worry about synchronizing multiple
>sources with the same, updated or new data.
Okay folks, I promised you a rant, and here it is.
<rant>As you can tell if you've read some of my other posts, I've been
doing this stuff for a while. The single thing that irritates me more
than anything else is the consistent confusion among some tech writers
between content and delivery.
SHOW ME THE CONTENT!!
I don't care if it's in Word, FrameMaker, or AmiPro. Even better, give
me ASCII text files.
Forget the damn format! I want to see the information. Forget the
fonts, forget the headers and footers, all that can be fixed ...
easily.
Make it good content. Good content is transparent. If it's good
content it should not matter what medium is used. It should not matter
what typeface is used. Paper size, screen ratios, use of color, are
all secondary to content.
I know that I am preaching to the choir. You folks wouldn't
participate on this list if you weren't dedicated to your craft. But
we've all seen manuals that are wonderfully designed. Manuals where
you read the same paragraph six times trying to figure out what it
means.
And we've also all seen products with a 10 page readme file that
covers everything you need to know clearly and succinctly.
Writing for single-source is a definable discipline with simple
guidelines. In addition to the benefits that Sean listed. Single
source content can be managed easily, translated faster, reduce
textual error rates, and help meet deadlines.
It drives me a little crazy to watch a technical writer fritter away
development time with some idiotic feature that Adobe has hidden in
the recesses of FrameMaker rather than getting content written.
It's good to be expert. I can make FM do things you can't imagine. But
that's the stuff you do before you start or after the content is in.
As a Doc manager, I would rather explain why we shipped an ugly
document than why we shipped an incomplete or erroneous one.
I am not saying that delivery systems don't matter. I am saying that a
mediocre delivery system with good content is useful, but an excellent
delivery system with faulty, incomplete, verbose, inconsistent content
is not just useless, it can kill a product. I have seen it happen.
And just to reiterate ... good content does not care how it is
presented.
</rant>
Whew, I feel better now. I'd better get back to work. What work?
Writing a book about the discipline of writing single-sourced
globalized content.
'tis true 8-D
-Doc
David W Lettvin
VerText
South Hamilton, MA
978-468-1105
It's a sobering thought that by the time Mozart was my age, he'd been
dead for five years. ?Tom Lehrer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
