ATTENTION ALL TECHNICAL WRITERS!

Subject: ATTENTION ALL TECHNICAL WRITERS!
From: Greg Owens <at756 -at- FREENET -dot- CARLETON -dot- CA>
Date: Fri, 8 Jul 1994 02:07:43 GMT

The idea for Writer's Block first emerged when the staff of NIVA
Inc., Canada's pioneer in technical documentation, developed its
company newsletter. As the newsletter grew in both scope and
popularity, we realized that a whole community of writers outside
NIVA might enjoy and potentially learn from the observations and
experiences of people working in the field.

Sharing experiences and communicating knowledge in entertaining
ways is what Writer's Block is all about. No matter what your
interest in writing may be, we are confident that Writer's Block
will provide the kind of information-sharing forum that you have
been looking for. So enjoy it, learn from it, and the next time
you get "writer's block"...remember, you're not alone.

Although this is the third edition of Writer's Block, it is the
first time that we have posted it on the FreeNet. Any questions,
comments, or suggestions are welcome.

While reading this issue, please keep in mind that all graphics,
font changes, accented characters, and other formatting
considerations had to be compromised in order to include Writer's
Block here. Anyone interested in receiving a hard copy of this
issue, or of any of the two back issues, can either reply to this
message, or write to the address provided at the end of this
posting.

----------------------------------------------------------------

WRITER'S BLOCK

"The Creative Reference for Today's Writers"

Volume 2 - Issue 1 (Summer 1994)

----------------------------------------------------------------

***From the Editor***

Good writing requires good organization. But being organized
doesn't happen by itself; it requires planning. While some
writers get by without planning, most people who write for a
living know that to get the best results, they need to plan their
efforts. This minimizes stress, and ensures that you are not
left scrambling at the last minute to complete tasks you
neglected to consider.

Depending on the nature and size of your task, planning can
require varying amounts of effort. While all projects require
some planning, the larger and more complex the project, the more
crucial planning becomes. Even what may seem to be the simplest
and most straightforward of tasks may not be determined as such
until you plan. In the long run, planning saves time. And time,
to a professional writer, is money.



This issue of Writer's Block deals with some of the many aspects
of planning as they relate to the writing process. So, before
you begin planning your next writing assignment, plan to read
this issue of Writer's Block.

---------------------------------------------------------------

***Cover Story***

Getting it Together--Organizing Your Writing Project (by Anton
Holland)

So you've just been assigned a new project. The thrill of a new
writing challenge takes hold of you. But your quickening pulse
may not be the result of your eagerness--it could be a
side-effect of something dark and foreboding. If the subject
matter is something that you're completely unfamiliar with, you
may be faced with what appears to be an insurmountable challenge.
As writers, we all worry about our credibility--and nothing is
more embarrassing than fashioning a message that highlights your
ignorance.

Now, when I mention knowing very little about the subject matter,
I'm not talking about having to bone up a little on something you
have a vague memory of from high school, like the economic
geography of Iceland or the First Law of Thermodynamics. The
type of knowledge deficit I'm referring to stems from something
completely beyond your scope of experience, something as
incomprehensible as song lyrics heard over AM radio, where the
cliche "in over your head" feels more like "six feet under". It
can be a very unnerving situation to realize that as hard as you
try, there seems to be no way that you can begin to grasp the
barest understanding of what you are supposed to write about.

If you dwell on your predicament too long, your confidence in
your own abilities will steadily erode to the point where all
your skills as a writer become inaccessible. In a situation like
this, one's first inclination is to panic, frantically casting
about for a solution with no real focus. This, in turn, can
reinforce your belief that you are not equipped to deal with the
challenge--and so the cycle continues, gathering momentum with
each iteration. This approach will inevitably lead to disaster,
as no real progress will be made in finding a useful solution to
your dilemma.

Everyone seems to "know" that the only way out of this
predicament is to take a methodical, systematic approach, and use
your lack of knowledge to give you a fresh perspective on a
subject that may be old hat to your audience. But many writers
have a great deal of difficulty implementing this strategy. I
try to use the following steps as a guide.

1. Stop panicking.


Living on the edge may work for poets and rock stars, but writers
who can't stop shaking run the risk of blowing their brains out.
Take a deep breath, go for a walk, watch your goldfish swim
around his bowl--anything to take your mind off the pressure.
Then get started and launch yourself into the task. Pick up any
reference material you have and start reading. Each bit of
information you expose yourself to will eventually provide some
insight into what you're trying to write about.

Once the first step is made, it will get easier to build the
momentum needed to drive your research and the development of
understanding.

2. Get yourself organized.

Organizing the task is half the battle. Go back to first
principles: what kind of a document are you supposed to write?
Who's the audience, and what kind of information might they need?
Based on the minimal knowledge you do have, determine what you
think should go into the document. Don't worry if you can't
answer all of these questions, or if the answers that you come up
with are way off the mark. Whatever you come up with at this
stage will give you a partial road map to what you have to go out
and find.

3. Look around for some background information.

Obtaining background information sounds pretty basic, but
sometimes a writer is given the impression that what's being
worked on is completely unique. Rarely does any writing project
evolve from a verbal vacuum--computer systems in large
organizations, for instance, are constructed on the basis of at
least some kind of design or specifications documents, which may
stem from a planning document, which in turn is geared towards a
proposed or established business process. Plans and reports are
often the culmination of a collection of meetings--for
which minutes have usually been taken--or flurries of memo
correspondence. Gather it all together, no matter how irrelevant
it may at first seem, study it, digest it.

4. Formulate your questions.

Analyze the information you've gathered, and try to determine
what kind of picture your background material paints. Does your
outline make any sense? Try to stitch the pieces of your
preliminary research together in order to get a broad overview of
the subject. Once you've achieved that perspective, more
specific, pointed questions may come to light.

5. Answer your own questions.

Once you've come up with a list of questions (which may be
extensive), try to focus on what seems to be most relevant.
Maybe the usefulness of your initial background material has been
exhausted and it's time to employ other conventional forms of
research. Answering your own questions may lead you to formulate
a new set of questions that, as a group, are more coherent
and sophisticated.

6. Use the knowledge of experts.

Even the most sophisticated questions still represent gaps in
your knowledge and understanding. There has to be somebody out
there that knows the answers to them. A major fear with many
writers is that of being perceived as asking stupid or irrelevant
questions that waste the time of your contacts and highlight your
ignorance of the subject. This is a valid concern, since such an
impression can seriously undermine your client's confidence.

Prepare yourself as well as you can so that you will ask the
right questions. See where your discussion is heading, and
rework your questions on the fly, if necessary, to keep them
relevant. Or try to convince the person that you're talking to
that some amount of ignorance is very useful, since it allows you
to approach the subject from a fresh perspective. To some
degree, this is an innate interpersonal skill. You'll just have
to trust your instincts.

7. Commit yourself to finishing the job.

By now you should have done plenty of information gathering.
Before your research collapses in on itself from its own gravity,
start churning out the pages. Review your outline and
reconstruct it if necessary. Create a table of contents. Get a
feel for your document by writing some of the introductory
material, and then jump right in.

Each time you use these steps to successfully complete a writing
project of this nature, you'll learn a little more about the
approach that suits you best--and you'll be better equipped to
handle the next challenge that comes along.

************

In the next issue of Writer's Block, Anton Holland will provide
advice to professional writers and editors faced with writing
challenges in a corporate setting. Planned topics in his new
column include effective modes of research, how to deal with
editorial differences of opinion, how to gain client confidence
in your expertise, and why you should always try to give clients
what they need, not just what they want.
----------------------------------------------------------------

***Feature***

Document Management (by Peter Vasdi)



The following is an excerpt from the April 1994 issue of HUM
Magazine.

When faced with the challenge of managing increasing numbers of
documents, organizations today often look to technology for the
whole solution, when technology is only a component of the
process. Even in the most straightforward situation, care must
be taken before proceeding with any technological solution since
traditional documentation principles still apply. In other
words, documents can only be effectively managed if they are
properly planned.

In government (and other large organizations) the number and
complexity of documents is overwhelming. Big documents. Small
documents. Groups of documents. Documents from correspondence
to forms to manuals to specifications. The ongoing effort to
manage the development, use, distribution, and maintenance of
these documents often leaves usefulness and quality of
information as afterthoughts--footnotes on the wish list of
document developers and users alike.

Technology is helping us to process, design, and manipulate text
and graphics at a rapidly increasing pace, particularly because
the tools are available to anyone with a computer. Technology is
also helping us distribute documents across greater distances
than ever, enabling users in the most remote locations to
receive, use, and even maintain their own documents. While
sophisticated document management technology can make this
process all the more efficient, potential for error grows. What
does the widespread availability of technology mean to the
integration of the documents being communicated? Furthermore,
what does it mean to "process effectiveness" as the amount of
information increases (because it almost never decreases)?

What is document management?

Document management is a process for organizing data, documents,
and information that allows for the evolution of these
documents--their creation, revision, status, and distribution
throughout a life cycle from days to decades. If implemented
properly, document management can make documents more accessible,
more accurate and up-to-date, easier to create, and easier to
use.

The fact that technology is so readily available, however, also
has the potential to cause problems. Product ads often make it
seem that technology is the answer to all your documentation
problems (excerpt from a recent review in Windows Magazine of an
on-line help creation product: "...you wind up with a document
that you can print as a sharp-looking manual with a full
index.... [It] can also become a help file--two documents for a
few hours work!").


The problem with technology is that it doesn't--can't--address
the most important aspect of documentation: the usefulness of
the information it contains.

Going on-line

Trying to put documents on-line typifies this problem. On-line
documents are often thought to be the perfect document management
solution--everyone can get at them, they are easy to update,
they save paper, and so on. Depending on the situation,
migrating paper-based documents to electronic format can be
important to the document management process. But this part of
the process should not be thought of as the entire process.

Michael Sutton, Director of Electronic Document Management
Systems for NUTAT Technologies, agrees. "Electrification", says
Sutton, "is one of the middle steps in the document management
process--not the first, and certainly not the last. Document
management is a life-cycle-long plan, not a one-time task.
Often, an on-line document is a document that has simply been
automated. But how does it communicate the documented
information? It's faster and it's electronic, but is it
useable?"

The printed page vs. the virtual page

When preparing to put a document on-line you have to first look
at the document as it exists on paper. How well-written is it?
Does it efficiently communicate the information? These are
critical questions because once a document is on-line we lose
many of the navigational landmarks we are used to. For example,
Sutton talks about the need to preserve the paper metaphor in an
electronic world. "We think in structured, hierarchical
pages--chapters, sections, paragraphs--and it's hard to shed that
skin. If you send a reader into the virtual page of an on-line
document, the spatial and navigational references are gone. It's
too amorphous for our linear thought streams."

When choosing a tool to help move documents to an on-line
environment, or to create documents for that environment, it is
important to consider not just the mechanical aspects of the
tool ("It goes from WordPerfect to MegaText in five seconds
flat!") but also the ultimate useability of the result. For
instance, annotation capability may seem a small thing; but many
can't do without it, and many on-line tools do not make allowance
for it (in any useful way).

And how about how we actually look up information? It is vital
that the classification and categories of search criteria are
carefully thought out, and that the control vocabulary and
lexicon are complete and thorough. One of the greatest benefits
of on-line documents is their ability to cross-refer, but only if
they are told to do so. It won't know a Toyota is a car, or that
China is part of Asia, unless you tell it so.


And then there's the serendipity factor. It's hard to flip
through a computer, or wander around on the hard drive, and just
happen upon the very thing you are looking for. But that very
technique is how we find much of the useful information we use
every day.

The point is, when planning an on-line project, plan not only how
to get the information on-line, but also how to use it once it is
there. Plan for cross-references, linear readers, annotation,
serendipity--all the things that make us feel warm and fuzzy
about paper-based documents. Your users, at least for now, will
need that security and frame of reference.

More than on-line access

On-line document access is only one aspect of document
management. Another aspect is the ability to know where to find
any document you or your department needs, how to get to that
document quickly, and how to be sure it's the most current
version. It means re-using information instead of reinventing
it, collaborating and coordinating document creation efforts, and
ensuring document security and integrity.

A document management system should be customized after careful
thought about your document needs and uses. For a small, one- or
two-person office, a three-drawer filing cabinet with a strong
lock might serve wonderfully; for a large government
organization, document management could involve mainframes,
imaging systems, a shelf full of tools, and a room full of
dedicated personnel. The main thing is that whatever method is
adopted, make it flexible enough to meet your current needs and
satisfy whatever might happen in the future, both within your
organization and the document management industry at large.

A spectre that haunts all purchasers of document-related
technology is compatibility. What if what I buy today isn't what
they're using tomorrow? What will allow the IT branch in Ottawa
to send their documents electronically to human resources in
Halifax, without the need to hire a truckload of computer techs
to make sure Halifax can read it? And what do I do with all
those documents I have in WordPerfect, MS Word, Ami Pro,
WordStar, PageMaker, and Interleaf.

A standard approach

The adoption of a standard can help your document management
efforts. One standard that's gaining acceptance industry-wide
for document creation and maintenance is the Standard
Generalized Markup Language (SGML). SGML stores data in an
application- and platform-neutral format; as your application
programs or platforms change over time, you will still be able to
access and manipulate your SGML data. Also, SGML is the only
standard (currently) for identifying and managing separate
components of a document. For instance, a paragraph about your
company's history can be created once, stored in one place, and
used in multiple documents, presentations, brochures, etc. SGML
doesn't worry about what the text actually will end up looking
like--it's format-neutral too. It leaves that to the specific
application used to manipulate the data.

A timely example of how SGML can help is the recent area code
change in Toronto (from 416 to 905 for a few million people).
The Canadian Construction Materials Centre publishes many
documents that rely on a data base of names and numbers (over
2,500 listings). The data base took three minutes to change
using a quick search-and-replace; however, the 283 documents that
use those numbers won't get changed quite as quickly. The group
is working on converting their data and documents to an
SGML-based system, a process that could literally change months
to minutes.

Above all else--plan

Even though document management can be said to have started with
the paper clip, it's a fairly new field in its current form.
There is a whole lot more to it than has been presented here, and
a whole lot it can offer if properly implemented. Plan, seek
advice, gain knowledge, get help, then plan some more.

Document management will continue to play a crucial role in the
success of organizations today and in the future. It is making
them more timely, more accurate, and more efficient, and helping
ensure that they keep current with competitors and clients. So
jump in--but jump carefully and with foresight, or you may end up
drowning in a sea of technologies and methodologies. In the
end, you'll be glad you took the plunge.

----------------------------------------------------------------

***Fiction***

Magic Bus (by John McGrath)

"Every day I get in queue. I get on the bus that takes me to
you..."

I doubt that the venerable rockers who penned this merry tune
ever rode the trans-suburban trails of Route 65, serviced by the
good old persons-in-blue of OC Transpo. Twice daily, five days a
week, fifty weeks a year, I participate in Ottawa-Carleton's
longest running saga-on-wheels.

Dutifully standing at attention at my stop, I wait for the
comforting sight of the hulking red and white automotive
behemoth. As I board the bus, I give the driver my customary
"hey, how ya doing" eyebrow. He nods his acknowledgement. Once
the formalities are over, I find myself transported from the
confines of a mere bus to a stage far removed from the
traditional venues of cultural enrichment.

I move swiftly to my usual seat at the back. From this vantage
point, I feel the power of a director, imparting insightful
information on each scene and character. As I settle into my
seat, the other players diligently take their places in
preparation for the bi-daily performance aboard Theatre 65.

The doors close with a thud. A chill ripples through me as the
lights dim. With a sobering jerk, the play begins, the sombre
morning light and the labouring growl of the engine providing an
appropriate backdrop for our journey.

Act I, enter Aphrodite, the goddess of love. Her undivided
attention centres on the passion-filled adventures detailed in
her latest novel, Fabio's Adventures in Amazonia. She dreams of
the heroic Fabio running his strong yet tender hands through her
Clairol tresses. Her generous make-up becomes a theatrical mask
that yearns for a semblance found only between the tempestuous
covers of romance novels. Air-brakes from somewhere below
interrupt the silence of her longing with whispers of "I love
you".

The spasmodic jarring of the doors opening signals the end of Act
I. Then, almost instantly, a polished character with a
fastidious eye for detail emerges through the roadside grime. It
is the exacting Mr. Meticulous. From his crafted corporate
appearance to his unobtrusive mannerisms, he exudes a careful
blend of robotic control and healthy organization. He reads The
Globe and Mail with methodical precision, folding the paper in
dizzying combinations to avoid intruding on his fellow players'
personal space. He works with the skill of an origami master in
an inspiring feat of paper manipulation. I wait for the day that
he will create a giant newsprint pterodactyl and send it
swooping down the centre aisle.

My eyes skim the crowd until I come across an urban-inspired
hybrid, the Good Old Boy Bros. This amiable pair of characters
combine the back-slapping good nature of country rubes with the
executive savvy of seasoned civil servants. They sit
side-by-side on the coral vinyl bench. Their shoulders form a
level plain of Harris tweed. The sparkle from their squinty eyes
is almost lost in the fleshy expanse of their jolly, purple
faces. They chuckle in deep baritone voices, the same
voices that close deals over T-bone steaks and draft beer. These
fellows lend a comic relief to the gravity of the play, much the
same as Falstaff indulges himself as the fool in the tragic Henry
IV.

The point in the performance that chills me to the depths of my
soul arrives. Enter the antagonist, Icarus Pretentious. He
swaggers onto the stage in tailored splendour, an aura of
arrogance and contempt surrounding him as he paces across the
stage. What's it going to be today, hotshot? The notebook
computer? Architectural Digest? Whatever it is, I hope it's not
the cellular phone, because I won't be able to contain my weary
disdain for your all too predictable ego.

I struggle with the stark emotions that the characters have
aroused in me by probing my most intimate sensibilities. As I
anxiously wait for the next development in the drama I discover a
wizened old man slumped in his seat. With a dazed expression he
stares into the chrome railing in front of him. A soul barren of
passion is reflected. What a pathetic sight: another disciple of
the corporate dogma that has stripped him of his ideals, his
pride. What does he have to look forward to besides regrets....

Wait, could this destitute soul be me? Am I subconsciously
moulding myself after an image that has already been cast? If
so, where do I fit into this grand theatrical tapestry? Can I
objectively evaluate my role in this production? If I could,
would it be similar to "man gets job; man shuffles papers; man
gets golden handshake"? Please, God, may the author of this
script be open to rewriting my character's destiny!

Ding! The familiar sound of the bell sends me spiralling through
the doors. The stage is alive with activity and the air is
filled with an encore of "excuse me's". The performance is over
and my fear subsides.

Next showing, 7.5 hours away.

Magic bus, magic bus, magic bus...

----------------------------------------------------------------

***Book review***

How To Talk So Kids Will Listen & Listen So Kids
Will Talk
by Adele Faber and Elaine Mazlish

Review by Peter Zvalo

Few things in life are more challenging than raising children.
While undoubtedly some aspects of parenting come intuitively to
many, other aspects do not. Sooner or later, every parent begins
to ask themselves such questions as "Am I being too strict?" or
conversely "Am I letting Johnny get away with murder?". There
are many books on the market that attempt to help parents answer
such questions.

Books on parenting have been around for many years, but much has
changed since the days of Dr. Spock's Baby and Child Care of the
1940s, both in the advice that is being given and in how
that advice is presented. How To Talk So Kids Will Listen &
Listen So Kids Will Talk, caught my attention because of its
descriptive title. A quick glance through the book, with its
many cartoons, further piqued my curiosity, and I don't even have
any kids.

Cartoons in a how-to book? You bet! In fact, I liked them so
much that I'm keeping them handy for future reference. These
cartoons are interesting because they depict various everyday
situations and the different ways in which they can be handled.
They demonstrate techniques on such things as how to listen and
understand your child's concerns, how to have cooperation in your
family without nagging, how to find alternatives to punishment,
and how to help a child attain a positive self-image. All of
this can be pretty heavy stuff, but when simplified into common
everyday situations it becomes easy to apply the suggested
techniques to the real world.

The book serves as a tool to retrain parents. It teaches parents
how to react to situations in a rational way and to view their
children as human beings in their own right with the same
capacity to be emotionally hurt by insensitive and derogatory
statements as any adult, if not more so.

The book contains various features that are designed to make the
parent think about how he or she presently handles difficult
situations and then goes on to suggest alternative ways that are
likely to be more effective and, in many cases, less damaging to
the child. Each chapter contains practical exercises in which
the reader is encouraged to write down his or her responses.
Each chapter also includes a summary page that parents are
encouraged to copy and put up in strategic locations around the
house as a reminder of the "correct" way of handling various
situations.

While admittedly, no one is likely to refer to these posted notes
in the heat of a stormy conflict, their very presence would
probably achieve the objective of making the parent think about
his or her actions.

The authors display sensitivity and use a common-sense approach
throughout the book. An example of this can be seen in the use
of pronouns. The use of the awkward "he/she, him/her,
himself/herself" was deliberately avoided in favour of loosely
alternating between use of male and female gender. In the words
of the authors, they hope that in doing so they have not slighted
either gender. They didn't.

How To Talk... teaches without preaching, and educates while
entertaining. It is not only enjoyable to read, but it also
teaches skills that can be applied in everyone's daily life. It
should be read by anyone who wants to learn about children, and
themselves.

----------------------------------------------------------------

***TV Mini-series Tells Tragic Tale of Dionne Quintuplets***

Production has begun on a two-part, television mini-series based
on the book Time of Their Lives: The Dionne Tragedy by John
Nihmey (NIVA Inc. President) and Stuart Foxman. A joint venture
of CBS and CBC, Million Dollar Babies, will star Beau Bridges,
Kate Nelligan, and French-Canadian actor Remy Girard.

The saga of the Dionne quintuplets remains one of the most
fascinating, yet tragic, human interest stories of the century.
Taken from their parents shortly after their birth in 1934, the
quints were made wards of the Ontario government, put on public
display before millions of curious tourists, and exploited into a
$500 million industry during the Depression. The book focusses
on Oliva and Elzire Dionne, and their eight-year battle with the
media, the government, and the public to regain custody of their
famous children.

Interest in the story of the Dionne quints was renewed in 1986
with the publication of Time of Their Lives. Written as a
fact-based novel, it was the first book to capture the tragedy of
the parents and reveal how greed and exploitation played key
roles in turning a fairy tale into a personal nightmare.

The film, produced by Bernard Zukerman and directed by Christian
Duguay, will air in the 1994/95 season. The screenplay, based on
the book, has been written by Suzette Couture.

----------------------------------------------------------------

The Writer's Block Bulletin Board will return in the next issue.

**************************
* Writer's Block *
* 800-180 Elgin Street *
* Ottawa, Ontario *
* K2P 2K3 *
* *
* Editor *
* Greg Owens *
* *
* Contributing Editors *
* Anton Holland *
* John Nihmey *
* Peter Zvalo *
* *
* Design *
* Jan Calnan *
* *
* Contributing Writers *
* John McGrath *
* Peter Vasdi *
* *
* Articles that appear *
* in Writer's Block do *
* not necessarily *
* reflect the views of *
* the publisher. *
* *
* Published by NIVA Inc. *
* *
* *
**************************


Previous by Author: Re: Step vs Task
Next by Author: Industry uses it
Previous by Thread: Re: How do you use WWW?
Next by Thread: Because you asked (both of you): Forum 95 info.


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


Sponsored Ads