HATs

["Jason Borchard" <Jason -dot- Borchard -at- sab -dot- wels -dot- net>]

All,

I was wondering if anyone could give some advice on which Help Authorization Tools work best?  I have downloaded six demos to try out: Help and Manual, RoboHelp, Doc-to-Help, WebWorks, AuthorIT, and Madcap Flare.  Which ones are the most common for converting documents (mainly Word) to online documentation?  Any input/resources/information would be greatly appreciated.


Jason Borchard
Technical Writer
WELS
techwriter -at- wels -dot- net

-----Original Message-----
From: techwr-l-bounces+jason -dot- borchard=sab -dot- wels -dot- net -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+jason -dot- borchard=sab -dot- wels -dot- net -at- lists -dot- techwr-l -dot- com] On Behalf Of techwr-l-request -at- lists -dot- techwr-l -dot- com
Sent: Tuesday, April 04, 2006 1:00 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: TECHWR-L Digest, Vol 6, Issue 4

Send TECHWR-L mailing list submissions to
	techwr-l -at- lists -dot- techwr-l -dot- com

To subscribe or unsubscribe via the World Wide Web, visit
	http://lists.techwr-l.com/mailman/listinfo/techwr-l
or, via email, send a message with subject or body 'help' to
	techwr-l-request -at- lists -dot- techwr-l -dot- com

You can reach the person managing the list at
	techwr-l-owner -at- lists -dot- techwr-l -dot- com

When replying, please edit your Subject line so it is more specific than "Re: Contents of TECHWR-L digest..."


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Try WebWorks ePublisher Pro for Word today! Smooth migration of legacy RoboHelp content into your new Help systems. EContent Magazine Decision- maker review (October 2005) is here: http://www.webworks.com/techwr-l

Doc-To-Help includes a one-click RoboHelp project converter. It's that easy.  Watch the demo at http://www.componentone.com/TECHWRL/DocToHelp2005

---


Today's Topics:

   1. Using a version control system with RoboHelp X5 (Gurpreet Singh)
   2. Re: Quaint technical writing (Geoff Lane)
   3. Re: Quaint technical writing (doc -at- edwordsmith -dot- com)
   4. Re: Quaint technical writing (Geoff Lane)
   5. Re: [Query] Your Experience(s) with AuthorIT (A)
   6. Re: quick question about 'hence' (Ken Munro)
   7. Quick question about 'hence'? (Geoff Hart)
   8. Re: Examples of Bad Technical Writing (Tony Markos)
   9. (no subject)
  10. Re: quick question about 'hence' (Lori Olcott)
  11. Re: Examples of Bad Technical Writing (Paul Pehrson)
  12. RE: Quick question about 'hence'? (Keith Hansen)
  13. Re: Boring documentation? (Julie Stickler)
  14. Re: Examples of Bad Technical Writing? (linda_sims -at- vanguard -dot- com)
  15. Boring documentation? (Hickling, Lisa (TOR))
  16. Re: Boring documentation? (Gene Kim-Eng)
  17. Re: [Query] Your Experience(s) with AuthorIT (William Gaffga)
  18. RE: Quick question about 'hence'? (Laurel Hickey)
  19. Re: [Query] Your Experience(s) with AuthorIT (Char James-Tanny)
  20. RE: quick question about 'hence' (Johan Hiemstra)
  21. I've landed (jposada)
  22. Re: Examples of Bad Technical Writing? (Janice Gelb)
  23. Re: quick question about 'hence' (Edwin Skau)


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

Message: 1
Date: Mon, 3 Apr 2006 12:30:00 +0530
From: "Gurpreet Singh" <gurpreet2311 -at- gmail -dot- com>
Subject: Using a version control system with RoboHelp X5
To: techwr-l -at- lists -dot- techwr-l -dot- com
Message-ID:
	<67afb4200604030000j6d0391c0n4116f112d44daae0 -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=ISO-8859-1

Hi All,

I wanted to ask few questions regarding the usage of a version control system with RoboHelp.

We basically have two motives for using a version control system:
1. To enable geographically distributed teams to work together on the same project 2. To maintain different versions (and a revision history) of the project files

Though, there is a version control system that comes with RoboHelp, called RoboSource Control, but is not a very good tool when it comes to enterprise level projects with geographically distributed TW teams.

The other option, which is recommended even in RoboHelp documentation, is to use Visual Sourcesafe.

Has anyone ever used any other version control system, such as VSS or Clearcase, instead of RoboSource control? Any suggestions over this, especially for the usage of Clearcase with RoboHelp?

Regarding the usage of a version control system for geographically distributed teams; has anybody ever used a multisite version control system, such as a Multisite Clearcase or a Multisite VSS? Any difficulties/problems faced in this type of setup?

Any suggestion over the usage of a multisite version control system with/without RoboHelp?

Thanks
Gurpreet Singh
New Delhi


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

Message: 2
Date: Mon, 3 Apr 2006 09:00:53 +0100
From: Geoff Lane <geoff -at- gjctech -dot- co -dot- uk>
Subject: Re: Quaint technical writing
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Message-ID: <38399837437 -dot- 20060403090053 -at- gjctech -dot- co -dot- uk>
Content-Type: text/plain; charset=us-ascii

On Monday, April 3, 2006, Dick Margulis wrote;

>> http://www.harborfreight.com/manuals/0-999/807.pdf
>>
>> I have to wonder if the environment that produced this is really in 
>> Pittsburg.
>> What do you think?

> What I think is that this was Ned's little April Fool's prank on 
> techwr-l. My guess is that the scan is of a manual printed in the 1950s.
---

My thoughts exactly at first. However, the URL given looks genuine and ten years ago I did work for a company who wouldn't replace pre-WWII manuals for cost reasons. For every old, but still sold product, they kept one (no longer pristine) master, which they photocopied as required!

--
Geoff



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

Message: 3
Date: Mon, 3 Apr 2006 04:19:45 -0700
From: doc -at- edwordsmith -dot- com
Subject: Re: Quaint technical writing
To: techwr-l -at- lists -dot- techwr-l -dot- com
Message-ID: <200604030419 -dot- 46004 -dot- doc -at- edwordsmith -dot- com>
Content-Type: text/plain;  charset="iso-8859-1"

On Sunday 02 April 2006 03:30, you wrote:
> > What do you think?
>
When I read it the first time, I flashed back on the early SNL skit by the Not 
Ready For Prime Time Players--John Belushi, in his role as the pirate Captain 
Ned, waxing sentimental about his sailor's life, always among 'manly, virile 
men.'

The writer of the manual probably refers to a similar estimable masculine 
cadre of toolmakers and tinkers, though the fog of quaintness obscures 
them--whether they be blacksmiths or technicians, I can't tell. At $12 per 
new torque wrench, we may never know. 

> What I think is that this was Ned's little April Fool's prank on
> techwr-l. My guess is that the scan is of a manual printed in the 1950s.

No. No! No one could have guessed it. Someone must have told you!  Drat drat 
drat, I must build higher walls.  And I too will hire resolute spies. 

Same time next year?

Ned Bedinger 
doc -at- edwordsmith -dot- com


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

Message: 4
Date: Mon, 3 Apr 2006 12:42:38 +0100
From: Geoff Lane <geoff -at- gjctech -dot- co -dot- uk>
Subject: Re: Quaint technical writing
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Message-ID: <149413142484 -dot- 20060403124238 -at- gjctech -dot- co -dot- uk>
Content-Type: text/plain; charset=us-ascii

On Monday, April 3, 2006, doc -at- edwordsmith -dot- com wrote;

>> What I think is that this was Ned's little April Fool's prank on
>> techwr-l. My guess is that the scan is of a manual printed in the 1950s.

> No. No! No one could have guessed it. Someone must have told you!  Drat drat 
> drat, I must build higher walls.  And I too will hire resolute spies. 
---

Hey Ned, you should also build or hire a better clock - you posted the
original on 2 April 01:00 UCT, which is five hours after the midday
deadline where you live (or, at least, the time zone for which your
computer is set!)

Cheers/.

-- 
Geoff



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

Message: 5
Date: Mon, 3 Apr 2006 09:26:42 -0400 (EDT)
From: "A" <aurora -at- identicloak -dot- com>
Subject: Re: [Query] Your Experience(s) with AuthorIT
To: techwr-l -at- lists -dot- techwr-l -dot- com
Message-ID: <MTE0NDA3MDgwMi5hdXJvcmE -dot- 1144070802 -at- dissimulo -dot- com>
Content-Type: text/plain; charset=iso-8859-1


David Dickerson said:
> Hello, everyone.
>
> I have done some research on the AuthorIT Web site at the URL,
> <http://www.author-it.com/>, and I am very impressed by what I
> have learned.
>
> Could any of you who use AuthorIT, or have used it, please share
> with me your experiences, good and bad? Assuming that my company
> can afford AuthorIT (and decides to purchase it), I would write
> printed documentation (out of Word 2003), create PDFs, and create
> on-line help for our flagship product, which is accessed by our
> users via a Web browser.

AIT does allow a pretty good single-sourcing environment. You can do
the things you've mentioned with relative aplomb. However, there are
snarls. AIT is restrictive in what it allows you to do with CSS and
its Javascript support is notoriously weak. There is NO documentation
on the internal structure of the SQL database that it uses and there
is NO support for real versioning. This means that if you are in a
software shop that creates multiple simealtaneous branches of code,
AIT makes your life sheer torment.

HTH,
A.u.r.o.r.a
             Yes, this is a humor site!
      --- www.adventuresindefecation.com ---
      Third-grade bathroom humor for everyone!


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

Message: 6
Date: Mon, 3 Apr 2006 11:56:35 -0300
From: "Ken Munro" <kenmunro -at- gmail -dot- com>
Subject: Re: quick question about 'hence'
To: "Johan Hiemstra" <webmaster -at- techexams -dot- net>,
	techwr-l -at- lists -dot- techwr-l -dot- com
Message-ID:
	<973d71e00604030756m2fba365fs7a431968f95f2542 -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=ISO-8859-1

Hi.

In my experience, hence throws people off a bit. I think it is indeed
a little archaic and people tended to wonder about it's meaning,
distracting from the message itself.

I'd say therefore, thus or so would be clearer. Keep it simple.

Cheers.

Ken Munro

--
email: kenmunro -at- gmail -dot- com
website: http://www.kenmunro.com/
podcast: http://www.kenmunro.com/kenmunro.rss


On 4/2/06, Johan Hiemstra <webmaster -at- techexams -dot- net> wrote:
> Hi all,
> I'm currently writing some articles about restoring cars, I just realized I
> tend to use 'hence' a lot in my writing. I think it just looks/fits better
> than 'so' for example. Just a personal preference I guess. I can use any of
> the other synonyms for "hence", but that feels a bit cheap and inconsistent.
> My actually question (being that English is not my mother's tongue): is
> 'hence' too old fashion or uncommon? I want to keep it simple because of the
> diverse audience.
>


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

Message: 7
Date: Mon, 03 Apr 2006 11:57:55 -0400
From: Geoff Hart <ghart -at- videotron -dot- ca>
Subject: Quick question about 'hence'?
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Message-ID: <30f285f4f24df1030c899f170efe5246 -at- videotron -dot- ca>
Content-Type: text/plain; charset=US-ASCII; format=flowed

Johan Hiemstra wondered: <<I'm currently writing some articles about 
restoring cars, I just realized I tend to use 'hence' a lot in my 
writing. I think it just looks/fits better than 'so' for example. Just 
a personal preference I guess.>>

It may also reflect dialect differences between American- and 
British-influenced English. Here in Canada, I see "hence" used 
sufficiently often in place of "thus" or "therefore" that I have to 
assume that this is fairly standard usage. My American wife (also an 
editor) disagrees, saying that she found the word a bit formal and 
possibly antique for American usage. She also noted that like me, she 
wouldn't change it unless explicitly instructed to do so by a project's 
style guide.

<<I can use any of the other synonyms for "hence", but that feels a bit 
cheap and inconsistent. My actually question (being that English is not 
my mother's tongue): is 'hence' too old fashion or uncommon? I want to 
keep it simple because of the diverse audience.>>

If you're using the word enough that you yourself are finding that it 
stands out, then you should consider cutting down on the usage and 
using other wordings. (I find in my own writing that I have to let it 
sit for several days between revisions for such repetition to become 
apparent to me.) That advice doubly true if you're writing for an 
American audience, since my very limited editorial sample size (me and 
my wife <g>) suggests it may be less appropriate for Americans.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart   ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
www.geoff-hart.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -



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

Message: 8
Date: Mon, 3 Apr 2006 09:09:54 -0700 (PDT)
From: Tony Markos <ajmarkos -at- yahoo -dot- com>
Subject: Re: Examples of Bad Technical Writing
To: Erin Cameron <ek_cameron -at- hotmail -dot- com>, techwr-l -at- lists -dot- techwr-l -dot- com
Message-ID: <20060403160954 -dot- 16377 -dot- qmail -at- web38208 -dot- mail -dot- mud -dot- yahoo -dot- com>
Content-Type: text/plain; charset=iso-8859-1

Erin:


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

Message: 9
Message-ID: <mailman -dot- 0 -dot- 1144130402 -dot- 5623 -dot- techwr-l -at- lists -dot- techwr-l -dot- com>

has the words "simple" or "easy" in it is going to be
non-sense - especially in the "Dummies" books.

This so common that, whenever I see "simple" or
"easy", I instinctively cringe.

Tony Markos

--- Erin Cameron <ek_cameron -at- hotmail -dot- com> wrote:

> Hi everyone,
> 
> I'm searching around for bad examples of technical
> writing (for some tech writing courses I am taking).
> I've found a few on the Web already, but thought I
> would pose the question here as well, since there is
> so much wisdom and experience on this list. Any
> examples of particularly flawed technical writing
> you would like to share?
> 
> I appreciate your input. Thanks so much!
> 
> Erin
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> WebWorks ePublisher Pro for Word features support
> for every major Help
> format plus PDF, HTML and more. Flexible, precise,
> and efficient content
> delivery. Try it today!.
> http://www.webworks.com/techwr-l
> 
> Doc-To-Help includes a one-click RoboHelp project
> converter. It's that easy.  Watch the demo at
> http://www.componentone.com/TECHWRL/DocToHelp2005
> 
> ---
> You are currently subscribed to TECHWR-L as
> ajmarkos -at- yahoo -dot- com -dot- 
> 
> To unsubscribe send a blank email to
> techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
> or visit
>
http://lists.techwr-l.com/mailman/options/techwr-l/ajmarkos%40yahoo.com
> 
> To subscribe, send a blank email to
> techwr-l-join -at- lists -dot- techwr-l -dot- com
> 
> Send administrative questions to lisa -at- techwr-l -dot- com -dot- 
> Visit
> http://www.techwr-l.com/techwhirl/ for more
> resources and info.
> 
> 


__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com 


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

Message: 10
Date: Mon, 3 Apr 2006 09:11:14 -0700 (PDT)
From: Lori Olcott <lori_olcott -at- yahoo -dot- com>
Subject: Re: quick question about 'hence'
To: techwr-l -at- lists -dot- techwr-l -dot- com
Message-ID: <20060403161114 -dot- 76888 -dot- qmail -at- web36409 -dot- mail -dot- mud -dot- yahoo -dot- com>
Content-Type: text/plain; charset=iso-8859-1

If you're writing for people restoring antique cars, they might like a
slightly old fashioned slant to the writing.  Just a passing thought.

Another question to ask is, how obvious is the post-hence instruction? 
Can additional cans of paint be assumed?  Personally, I prefer to spell
out as much as possible.  But leaving it out is an option.

Does the post-hence instruction prompt for more information?  If so, it
might need its own sentence.

ÃâÅFor lighter colors, you will usually need more layers of paint,
generally an additional %40 over your expected quantity of paint cans. 
For white or pale yellow, you might need as much as %50 more paint for a
consistent finish."

> My actually question (being that English is not my motherÃââs tongue):
is
> ÃâËhenceÃââ too old fashion or uncommon? I want to keep it simple
because of
> the diverse audience.
>ÃâÅFor lighter colors, you will usually need more layers of paint, hence 
>more paint cans.ÃâÂ

 

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com 


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

Message: 11
Date: Mon, 3 Apr 2006 10:33:23 -0600
From: "Paul Pehrson" <paulpehrson -at- gmail -dot- com>
Subject: Re: Examples of Bad Technical Writing
To: techwr-l -at- lists -dot- techwr-l -dot- com
Message-ID:
	<c0ca6e5c0604030933i3a50b966tf279d96600e3116 -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=ISO-8859-1

Erin,

My supervisor recently acquired an MP3 player whose instruction manual
was poorly translated. Here are some excerpts from the manual:

---

Do not use this device in the extremely thermal, cold, dusty, and
watery circumstances..

More simple under FM interface, it only can do until the 3rd step and
deleted is present channel. Please plug the USB cable out after the
safe injection when delete the files in the computer. Otherwise it
will show that the file has not been deleted.

Warning: This program can just be used by the person who is
professional to repair this machine. This upgrade maybe can cause the
machine can not work again because of the incorrect operation.

The normal MP3 user can be troubled by 'Material Leakage' and they
would not like others to read themselves' personal data', they only
can delete this 'private data' when their friends borrow their Mp3,
which it cause big trouble.

Firstly, the user can see the format tool, select 'Partition and
password protect' and select the suitable space for the password
protected disk and then set up username and password, input 'New
username' in inputting username, input 'new password' in the inputting
password, after confirming 'new password', click 'start', then it
start to divide disk.

Remark: When connecting PC with player to transfer data, any operation
is forbidden. During this period, do not get out the USB in order to
avoid data transferring not completely or player damage.

There is some noise in the damaged MP3 and even can not play music,
please assure that the file is complete.

---

In any case, if you are interested, I photocopied the whole manual and
kept it for reference. If you want to contact me off list, I'd be
willing to fax it to you. (Its 10 pages long.)

It is probably a better example of bad translation, but because I
can't hardly make heads nor tails of the information, it comes across
as bad technical writing as well.


Paul Pehrson
Midvale, UT




--- Erin Cameron <ek_cameron -at- hotmail -dot- com> wrote:

> Hi everyone,
>
> I'm searching around for bad examples of technical
> writing (for some tech writing courses I am taking).
> I've found a few on the Web already, but thought I
> would pose the question here as well, since there is
> so much wisdom and experience on this list. Any
> examples of particularly flawed technical writing
> you would like to share?
>
> I appreciate your input. Thanks so much!


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

Message: 12
Date: Mon, 3 Apr 2006 11:59:14 -0500
From: "Keith Hansen" <KRH -at- weiland-wfg -dot- com>
Subject: RE: Quick question about 'hence'?
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Message-ID:
	<B4DBD1887147DE4BBAB1CBD0C1C99AD93C8BBE -at- wfg-win2k3-exch -dot- WFG -dot- LOCAL>
Content-Type: text/plain;	charset="us-ascii"

 
Geoff wrote:

"It may also reflect dialect differences between American- and
British-influenced English. ... My American wife (also an editor)
disagrees, saying that she found the word a bit formal and possibly
antique for American usage." 

Agreed.  To my American ears, "hence" does sound slightly old fashioned,
although not wrong.  Words such as "therefore/thus/so" certainly sound
more natural to me.  I suspect "hence" was more common in American
writing 50 years ago than today.

"Hence" may be fine for the British, along with their "whilst" and
"amongst," which caused a furor here some time ago!  (Barely ever hear
an American use either of those...)

Keith


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

Message: 13
Date: Mon, 3 Apr 2006 15:58:13 -0400
From: "Julie Stickler" <jstickler -at- gmail -dot- com>
Subject: Re: Boring documentation?
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Message-ID:
	<5eda48240604031258h726307e9iff0983adf842f9bd -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=ISO-8859-1

Every time we start another thread about "interesting" manuals,
writing styles, making the documentation "accessable" and so on I have
to wonder, does anyone on this list localize their documentation?

We translate our documentation into about a dozen languages, and many
of the guidelines for writing for a global audience are in direct
opposition to writing a folksy,  Dummies-style book.  We're supposed
to write short, clear sentences.  We're supposed to avoid humor
because it doesn't translate.  Avoid examples like sports metaphors
that might not be understood by other cultures.  If I want to stay on
the good side of our localization manager, I CAN'T write a book that
looks anything like one of the Dummies books.

I don't write formal manuals because I am incapable of writing an
interesting book.  I do it because that is the writing style that best
meets the needs of both my users and the company that employs me as a
writer.

Julie Stickler


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

Message: 14
Date: Mon, 3 Apr 2006 16:11:04 -0400
From: linda_sims -at- vanguard -dot- com
Subject: Re: Examples of Bad Technical Writing?
To: " TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Message-ID:
	<OFCD7B7F2F -dot- A61414AB-ON85257145 -dot- 006EA032-85257145 -dot- 006EE09E -at- vanguard -dot- com>
	
Content-Type: text/plain; charset="US-ASCII"

Erin Cameron wrote on 04/02/2006 03:12:34 PM:

> Hi everyone,
> 
> I'm searching around for examples of bad technical writing (for some
> tech writing courses I am taking). I've found a few on the Web 
> already, but thought I would pose the question here as well, since 
> there is so much wisdom and experience on this list. Any examples of
> particularly flawed technical writing you would like to share?
> 
> I appreciate your input. Thanks so much!

A good source of examples can be found here:

http://www.techstandards.com/contest.htm

They have a yearly contest for the Worst Manual (too late to submit for 
this year).

I believe all the submissions must come from publicly available 
documentation, so there are (probably, but I'd check as IANAL) no 
copyright issues.
CONFIDENTIALITY STATEMENT. The information contained in this e-mail message, including attachments, is the confidential information of, and/or is the property of, Vanguard. The information is intended for use solely by the individual or entity named in the message. If you are not an intended recipient or you received this in error, then any review, printing, copying, or distribution of any such information is prohibited, and please notify the sender immediately by reply e-mail and then delete this e-mail from your system.



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

Message: 15
Date: Mon, 3 Apr 2006 15:41:21 -0500
From: "Hickling, Lisa (TOR)" <lhickling -at- Express-Scripts -dot- com>
Subject: Boring documentation?
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Message-ID: <7F11F373F7DCD311806200805FBEB72106732D07 -at- TORMS001>
Content-Type: text/plain; charset=us-ascii


Well said Julie! When you are a lone writer on a unilingual/unicultural
project, it's fun, possible and appropriate to explore your creative
side without fear of retribution. However, this may lead to disaster in
globalized docs. Knowing that cute might backfire, I think twice about
appearing too familiar or folksy in documents that are to be translated.


Then too on multi-author projects, there is the added overhead required
to harmonize each writer's take on humor and interest into the one cool
voice that makes it all work.

Lisa H.
GTA, Ontario 


-----Original Message-----
From: Julie Stickler
Sent: Monday, April 03, 2006 3:58 PM

Every time we start another thread about "interesting" manuals,
writing styles, making the documentation "accessable" and so on I have
to wonder, does anyone on this list localize their documentation?

We translate our documentation into about a dozen languages, and many
of the guidelines for writing for a global audience are in direct
opposition to writing a folksy,  Dummies-style book.  We're supposed
to write short, clear sentences.  We're supposed to avoid humor
because it doesn't translate.  Avoid examples like sports metaphors
that might not be understood by other cultures.  If I want to stay on
the good side of our localization manager, I CAN'T write a book that
looks anything like one of the Dummies books.

I don't write formal manuals because I am incapable of writing an
interesting book.  I do it because that is the writing style that best
meets the needs of both my users and the company that employs me as a
writer.

******* Confidentiality Notice *******
ESI Canada -- Optimizing the value of drug and dental benefits

This email, its electronic document attachments, and the contents of its website linkages may contain confidential health information.  This information is intended solely for use by the individual or entity to whom it is addressed.  If you have received this information in error, please notify the sender immediately and arrange for the prompt destruction of the material and any accompanying attachments.

******* Avis de confidentialite *******
ESI Canada -- Optimiser la valeur des regimes d'assurance medicaments et dentaires

Ce courriel ainsi que tout document y etant joint de meme que le contenu des liens vers des sites Web peuvent reunir des renseignements  confidentiels sur la sante.  Cette information s'adresse uniquement a l'usager ou a l'organisation auxquels elle est destinee.  Si vous avez recu ce message par erreur, veuillez en aviser l'expediteur immediatement et proceder a la suppression du document et des fichiers joints sans tarder. 






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

Message: 16
Date: Mon, 3 Apr 2006 14:03:21 -0700
From: "Gene Kim-Eng" <techwr -at- genek -dot- com>
Subject: Re: Boring documentation?
To: "Julie Stickler" <jstickler -at- gmail -dot- com>,	"TECHWR-L"
	<techwr-l -at- lists -dot- techwr-l -dot- com>
Message-ID: <001201c65762$0a672060$3a20c90a -at- viragelogic -dot- com>
Content-Type: text/plain; format=flowed; charset="iso-8859-1";
	reply-type=original

My current company does not localize, but my last two did. 
The only users who ever expressed a desire for documents 
that were "less formal" were native English readers (to be
exact, US readers).  The sole exception to this was in some
manufacturing environments in Asia where the average worker
was relatively uneducated.  IMO, the desire for "less formal" 
documents primarily results from a combination of poor reading
ability plus poor self-discipline in the US.  Users elsewhere in 
the world seem to understand that the reason for reading 
product manuals is to use the product and not to entertained.

Gene Kim-Eng


----- Original Message ----- 
From: "Julie Stickler" <jstickler -at- gmail -dot- com>

We translate our documentation into about a dozen languages, and many
of the guidelines for writing for a global audience are in direct
opposition to writing a folksy,  Dummies-style book.  



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

Message: 17
Date: Mon, 3 Apr 2006 14:25:28 -0700
From: William Gaffga <WilG -at- GibbsCAM -dot- com>
Subject: Re: [Query] Your Experience(s) with AuthorIT
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Message-ID: <E9EEEBB2-F669-40E5-A7FC-3B658E4E3E5D -at- GibbsCAM -dot- com>
Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed

On another list I mentioned I was looking at AuthorIT as a transition  
option from FM for Mac, thinking that if I need to move to PC, why  
not re-evaluate our tools. One list member replied that 6 months ago  
they tried a 4 license pilot project in AuthorIT, to check out the  
app. They found that AuthorIT performed poorly in a network  
environment but was fine for small projects with a single author,  
which I found very surprising considering this is supposedly one of  
AuthorIT's strengths. Also, they found that AuthorIT's PDFs are text  
& graphics only, it cannot produce hyperlinked PDFs under any  
condition. This makes it totally unsuitable for cross-references.  
LAstly, the support was poor. They had some suspected bugs and  
AuthorIT could not reproduce the bugs because they did not have a  
networked testing setup. Once they made a networked environment they  
found and fixed the bug. This also really surprised me considering it  
is sold as a networked product. The poster on the other list  
suggested I wait a few years until they had a more stable and usable  
product.

All of this is second hand so take it as you will.

Will.


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

Message: 18
Date: Mon, 3 Apr 2006 15:31:16 -0700
From: "Laurel Hickey" <lhickey -at- 2morrow -dot- bc -dot- ca>
Subject: RE: Quick question about 'hence'?
To: "'Keith Hansen'" <KRH -at- weiland-wfg -dot- com>,	"'TECHWR-L'"
	<techwr-l -at- lists -dot- techwr-l -dot- com>
Message-ID: <000001c6576e$53839830$4133fea9 -at- 2morrow>
Content-Type: text/plain;	charset="us-ascii"

Does anyone here want "cans of paint" rather than "paint cans"? 

I also agree that more information is needed, for exampe, the percent more
paint required for adequate coverage using lighter colours over.... what?
Dark colours? And, how is the estimating being done anyways? Why assume the
estimate is done using a mid-range or darker paint? 

Estimate based on coats of paint and specify how many coats will be needed
for light, mid and dark colours over a mid-range colour as a baseline? And,
for what surface? Smooth? Rough? 

Laurel, who has spent entirely too much time running back to paint stores
for more cans of paint AND who has given away cookies in brand new unused
paint cans that my paint store also sells, hence .....

-------------------------------------
Laurel Hickey
2morrow writing & document design
lhickey -at- 2morrow -dot- bc -dot- ca
http://www.2morrow.bc.ca




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

Message: 19
Date: Mon, 3 Apr 2006 18:57:18 -0400
From: "Char James-Tanny" <charjtf -at- gmail -dot- com>
Subject: Re: [Query] Your Experience(s) with AuthorIT
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Message-ID:
	<c0ef8fb70604031557m5eea7435g9a1fc811a3daeb8a -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=ISO-8859-1

Hi, Will :-)

> On another list I mentioned I was looking at AuthorIT as a transition
> option from FM for Mac, thinking that if I need to move to PC, why
> not re-evaluate our tools. One list member replied that 6 months ago
> they tried a 4 license pilot project in AuthorIT, to check out the
> app. They found that AuthorIT performed poorly in a network
> environment but was fine for small projects with a single author,
> which I found very surprising considering this is supposedly one of
> AuthorIT's strengths.

It seems to depend on how the user is connected to the network. For
one of my contracts, I have to VPN into the server, and so my
connection runs slower than if I could connect directly. (They've also
found a problem with my VPN connection that was causing the problem,
so once that gets fixed, I should be able to work a bit quicker.)

For those folks who can connect directly to the server, there's no
performance hit.

> Also, they found that AuthorIT's PDFs are text
> & graphics only, it cannot produce hyperlinked PDFs under any
> condition. This makes it totally unsuitable for cross-references.

Right now, AIT uses Distiller, not PDF Maker, when publishing directly
to PDF. (This should change.) However, it is possible to publish to
Word and then to PDF, in which case all links and bookmarks are
preserved. (This is how I produce PDFs.)

> LAstly, the support was poor. They had some suspected bugs and
> AuthorIT could not reproduce the bugs because they did not have a
> networked testing setup. Once they made a networked environment they
> found and fixed the bug. This also really surprised me considering it
> is sold as a networked product. The poster on the other list
> suggested I wait a few years until they had a more stable and usable
> product.

That sounds wrong, but I don't work for their support department ;-) I
know they haven't documented using SQL well, but most folks get
answers right away. They've had a network testbed for awhile now,
although I can't tell you exactly how long...I didn't use a network
for the first several years.

And the tool was originally released 10 years ago. Many folks consider
it quite stable and usable. (I have clients who routinely produce
large Word documents, Web sites, and HTML-based Help with few or no
problems.

This doesn't mean that it's perfect, but I'm still looking for
software that is ;-)

David, to answer your original question, my Web site
(http://www.helpstuff.com) is published from an AIT database (JET).
Other samples are listed at
http://www.authorit.com/index.mv?contentexamples.

Char James-Tanny ~ JTF Associates, Inc. ~ http://www.helpstuff.com
----------------------------------------------------------
Please send follow-up questions to the list.
Contact me directly (CharJT at helpstuff dot com) with business inquiries.
----------------------------------------------------------
2005-2006 Microsoft Help MVP ~ MSHelpWiki http://www.mshelpwiki.com
AuthorIT Certified Consultant, Development, and Training
Moderator, HATT and MSHelp2
STC Candidate for Secretary
STC Online Information SIG: Online Help Lead
Web site Hosting and Design ~ http://www.jtfhosting.com


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

Message: 20
Date: Tue, 4 Apr 2006 01:03:03 +0200
From: "Johan Hiemstra" <webmaster -at- techexams -dot- net>
Subject: RE: quick question about 'hence'
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Message-ID: <200604040004 -dot- k3404I120413 -at- gaea -dot- techexams -dot- net>
Content-Type: text/plain;	charset="windows-1250"

Thanks for the many public and private responses to my question. 

I like Bonnie's suggestions "and therefore" and "and thus" a lot, partly
because it removes the comma and gives a nice flow to the sentence. But all
credit goes to the word 'and' in those suggestions, as "therefore" and
especially "thus" has a similar old-English Shakespeare sound to it like
"hence" . And I'm not particularly looking for suggestions for when to
replace a comma with 'and'. Although all suggestions are welcome. :)

Thanks also for the other alternatives suggested by others, even for the
spelling corrections in my message. Forgive me for not making the same
spelling and grammar efforts for my email messages and posts. ;)

I think I'm going to go with Heidi's suggestion and use 'so' more often,
considering the audience, which as I mentioned in my initial message, is
very divers. And partly in response to a private reply: I haven't
'researched' the audience because I know it already. (I'm betting someone
feels the urge to respond to that ;)). The articles are for a website about
fixing and tuning cars by yourself, not just restoring expensive old-timers.
So the audience ranges from 16-year-old kids to pensioned brain surgeons.
Additionally, it will have an international audience, which is one of the
main reasons for asking the question. I like the word 'hence', but I can
imagine that for many people in the audience it is too sophisticated etc.

I own the site, so I don't have an editor (now that's certainly going to get
a response). I'm creating this site because I knew jack about cars 2 weeks
ago, and don't want to get ripped off by car dealers anymore. ;) Plus I want
to make some 'changes' on my own car. So, the site gives me an excuse to dig
into it 'and' practice writing in other areas than IT certifications. I'm
sure an editor could make plenty of improvements, and 'if' I get any
commercial plans with it I'll probably get one too.

Also forgive me for not giving individual responses to the answers that had
more to do with the subject than the word "hence". It is just a single
sentence from an entire paragraph about how much paint one would need, and
from a 1500-words article. I don't want to sound touchy because I took no
offense or whatsoever, but of course one needs more information than just
that one sentence. Nevertheless, here's the entire paragraph (first draft!):

"When you found the matching paint, you will need to determine how much
paint you need.  Generally, you will need more paint than you would expect,
especially when using spray cans. Using too little paint will also result in
a color difference, even if you did find a perfect match. For lighter
colors, you will usually need more layers of paint, hence more paint cans.
On average, you will need 3 to 5 layers of paint to get the color right, and
depending on the size of the body part you are painting, a single can will
hardly be enough to cover just a single layer. Try to buy sufficient paint
at once, so the cans will be from the same batch or custom mix."

Did I already mention I'm partly doing this for practice? ;) That includes
expanding my vocabulary on non-IT jargon. A 'can of paint', I'm referring to
"spray cans". I'm not sure that's correct either, but I'll be able to solve
any translation issue in terminology during research and fact checking. Hey,
I don't want to bother you with translation issues.

Again, I very much appreciate all the replies I received!




-- 
No virus found in this outgoing message.
Checked by AVG Free Edition.
Version: 7.1.385 / Virus Database: 268.3.5/300 - Release Date: 4/3/2006
 



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

Message: 21
Date: Mon, 3 Apr 2006 21:03:17 -0400
From: "jposada" <jposada01 -at- yahoo -dot- com>
Subject: I've landed
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Message-ID: <00a901c65783$8f643840$6401a8c0 -at- John>
Content-Type: text/plain; format=flowed; charset="iso-8859-1";
	reply-type=original

Hi, guys...looks like I've landed at a position after having been laid off 
the beginning of March.

I'll save the name until I actualy report to work (next week), but sufice it 
to say it is an employee position with a VERY large information storage and 
management organization with FrameMaker as the enterprise authoring 
platform.

Being an employee in a large organization, its time to see how the other 
half lives.

John Posada
Primary Technical Writer 



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

Message: 22
Date: Tue, 04 Apr 2006 11:33:40 +1000
From: Janice Gelb <janice -dot- gelb -at- sun -dot- com>
Subject: Re: Examples of Bad Technical Writing?
To: techwr-l -at- lists -dot- techwr-l -dot- com
Message-ID: <4431CCF4 -dot- 8050806 -at- sun -dot- com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed

linda_sims -at- vanguard -dot- com wrote:
> 
> A good source of examples can be found here:
> 
> http://www.techstandards.com/contest.htm
> 

Seems to me this contest should be divided to
differentiate between English documentation written
by people who should know better and obviously
badly translated manuals or those written by people
whose native tongue is obviously not English. (I
always figure I wouldn't be able to do any better
if I had to write in Japanese using a dictionary!)

-- Janice


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

Message: 23
Date: Tue, 4 Apr 2006 10:40:03 +0530
From: "Edwin Skau" <eddy -dot- skau -at- gmail -dot- com>
Subject: Re: quick question about 'hence'
To: "Johan Hiemstra" <webmaster -at- techexams -dot- net>
Cc: techwr-l -at- lists -dot- techwr-l -dot- com
Message-ID:
	<a5fe7370604032210w7fc44cd1l492c0404aec69ff7 -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=ISO-8859-1

On 4/4/06, Johan Hiemstra <webmaster -at- techexams -dot- net> wrote:
>
> Thanks for the many public and private responses to my question.
>
> And I'm not particularly looking for suggestions for when to
> replace a comma with 'and'. Although all suggestions are welcome. :)
>
>
Because that sounds like an invitation: the best time to replace the comma
with 'and,' if required, is before you publish the document.

;-)

Edwin


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

_______________________________________________
You are currently subscribed to 
TECHWR-L.
To unsubscribe send a blank email to 
http://lists.techwr-l.com/mailman/listinfo/techwr-l
Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit 
http://www.techwr-l.com/techwhirl/ for more resources and info.

End of TECHWR-L Digest, Vol 6, Issue 4
**************************************

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content 
delivery. Try it today!. http://www.webworks.com/techwr-l 

Doc-To-Help includes a one-click RoboHelp project converter. It's that easy.  Watch the demo at http://www.componentone.com/TECHWRL/DocToHelp2005

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.