RE: Of myth and reality

Subject: RE: Of myth and reality
From: "John Locke" <mail -at- freelock -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 19 Jul 2002 11:51:01 -0700 (PDT)

Steve Jong wrote:
> If you're writing the same block of text twice,
> you have a problem. But if nothing else, the graphical demands (or at
> least styles) of printed and online documentation seem irreconcilable:
> you can't have too many graphics in a document, and you pretty much
> can't have graphics online (or so you all say 8^) The printed version
> is apparently the "fat" one!

Why *can't* you have graphics online? I do it all the time! I fail to see
the problem.

I generate Visio diagrams to illustrate conceptual information. This goes
both online and in printed docs. I sometimes include screenshots
substantially reduced, with call-outs drawing the reader's attention to
what I'm trying to point out to them. I fail to see why this is poor
practice in online documentation.

Sure, it helps to provide higher resolution versions for the printed
documentation, but for the most part, the same content goes into both my
printed and my online docs.

Apparently, though, I do my documentation from an opposite approach than
many on the list. Rather than starting with a Word or Frame document, and
then attempting to move it to the web, I start with a web site, and move
it to a printed version when it's relatively stable. I design the web
documentation from the ground up, with appropriate links, chunked for easy
online reading, but sequenced in a way that provides context. At least
that's my goal... whether I succeed or not is another issue...

I prefer online documentation to printed docs for the following reasons:

1. It is (or should I say, can be) more up to date.
2. It can provide links to other sources for learning about the issue,
without having to go buy another book.
3. I can search for key words and jump into the topics I'm looking for--or
find related topics easily.

Now, before you tell me that printed docs are way better, let's take a
look at some of their advantages--and ways to address these advantages in
online docs:

1. You can spread it out in front of you, and refer to it while you work
on the computer.
(Thanks to Windows XP, a recent laptop, and an extra monitor, I can put
the online material on one monitor and write on the other.)

2. You can write notes on paper, provide corrections, etc.
(A well-designed site can provide a mechanism for users to contribute
comments, essentially allowing for collaborative notes... a
well-maintained site can be updated nearly instantly.)

3. You can read it outside, in bright sunlight.
(Okay, I don't have an answer for this one. But you can read in the dark,
with no other light source... does that turn you into a mole?)

I guess this is all a roundabout way of saying in all of these
advantages/disadvantages, one thing that doesn't have to change is the
actual content. Sure, each medium has its strengths, and absolutely, you
should organize your information around those strengths... but my opinion
is that good content is good content, wherever it may be. You don't have
to make it "lite" for the web.


John Locke
Owner, Freelock, LLC

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

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 for more resources and info.

RE: Of myth and reality: From: SteveFJong

Previous by Author: Re: Link Sniffer?
Next by Author: Re: Help! Relative links in MS Word
Previous by Thread: RE: Of myth and reality
Next by Thread: RE: Of myth and reality

What this post helpful? Share it with friends and colleagues:

Sponsored Ads