Re: Tech. writing as parables? Japanese style

Subject: Re: Tech. writing as parables? Japanese style
From: Wayne Douglass <wayned -at- VERITY -dot- COM>
Date: Wed, 6 Aug 1997 14:04:18 -0700

geoff-h -at- mtl -dot- feric -dot- ca writes:
|> Wayne Douglass wondered <<Yeah, but try writing a technical
|> manual in the form of parables and see where that gets
|> you.>>
|>
|> Actually, it gets you employed as a tech. writer in Japan
|> if what I've read is any indication. That's not intended as
|> a slap, but rather as an introduction to a question. I've
|> always read that Japanese technical style differs
|> dramatically from English style: English cuts right to the
|> chase and states things explicitly, whereas Japanese
|> circles around the issue, never confronts it directly, but
|> nonetheless leads you to the correct place... or so "they"
|> say. (Tie-in: that sounds a bit like parables to me.) Can
|> anyone who works in Japan confirm this, or elaborate (e.g.,
|> provide an example)?

Somehow I missed Geoff's interesting question in the stream of postings, but
I am almost convinced that some technical topics are *best* explained as
parables rather than the usual Joe Friday "just the facts" approach. Of
course, if you've bought Whiz-Bang Pro, the Swiss Army Knife of application
software, you expect the usual reference/procedural approach to explain how
to use it. But a Zen approach would be to ask yourself what state of
consciousness would cause you to want to use Whiz-Bang Pro in the first
place. How many applications could stand up to that scrutiny?

Recently I was assigned to write an online document on searching as an aid
to users of our search engine. I jokingly referred to it as "Zen and the Art
of Formulating Queries," and I even started off the review draft with a Zen
parable. It turned out that I was smarter (read "more enlightened") than I
knew - because searching *is* a Zen discipline. (For example, if you already
know the answer, you can formulate the perfect query!) This approach led me
to write the second-best sentence I have ever composed in technical writing:
"The journey is the reward and it begins with the first step, but if you
meet the Buddha on the road, kill him." Alas, this threw the reviewers
completely off track - an object lesson in avoiding humor in technical
documentation.

The best sentence I have ever composed in technical writing also came from
this assignment: "'What is the sound of one hand clapping?' is just another
query."



--Wayne
---------------------------------------------
Wayne Douglass phone: 408-542-2139
Verity, Inc. FAX: 408-542-2040
894 Ross Road mailto:wayned -at- verity -dot- com
Sunnyvale, CA 94089 http://www.verity.com
"Connecting People With Information"
---------------------------------------------

TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html


Previous by Author: Job open, Silicon Valley: TW for HW/SW
Next by Author: Re: Using capital letters
Previous by Thread: Re: Tech. writing as parables? Japanese style
Next by Thread: Re: Tech. writing as parables? Japanese style


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


Sponsored Ads