Re: techwr-l digest: March 10, 2000

[JBauman -at- Safety-Kleen -dot- com]

Hello!

I'll be out of the office on Monday, March 13, 2000 through Thursday, March 16,
2000.  I'll be back on Friday, March 17th, and then I'll be able to respond to
your message .


=======================================
Jim Bauman
IS---Lotus Notes Application Development
=======================================

In response to:



Sponsored by Weisner Associates Inc., Online Information Services
Training & consulting for RoboHELP, Dreamweaver, HTML, and HTML-Based Help.
More info at http://www.weisner.com/train/ or mailto:training -at- weisner -dot- com -dot- 

Your web site in 32 languages? Maybe not now, but sooner than you think.
Contact ForeignExchange for the FREE paper, "3 steps to successful
translation management" (http://www.fxtrans.com/3steps.html?tw).
_________________________________________
TECHWR-L Digest2 for Friday, March 10, 2000.

1. Re: Updating foreign language translations
2. Re: Ideas in motion
3. FW: Question on Professional development policy?
4. Re: Ideas in Motion
5. Updating foreign language translations?
6. RE: Question on Professional development policy?
7. RE: Ghost Writing/Publication Credit
8. OT: need a computer
9. A vs an
10. RE: The Real Offense
11. Re: Old thread, hopefully new spin on "allow" v. "enable.
12. Re: Curious printing problem (PRN files)
13. RE: punctuation and procedure titles...
14. Re:  Clarification (was Real Offense)
15. RE: Ideas in Motion
16. RE: A vs an
17. RE: Web help tools - review
18. RE: Updating foreign language translations
19. Question for Contractors
20. tech writers and knowledge bases
21. Re: Ckarification (was Real Offense)
22. RE: The Real Offense
23. Re: Massively Automated Intranet
24. URGENT: graphics printing oddly
25. RE: Question for Contractors
26. Re: CLarification (was Real Offense)
27. Blue Collar Tech Writers
28. RE: Ideas in Motion
29. Re: Ideas in Motion
30. RE: The Real Offense
31. Re: Question for Contractors
32. on "CAN", was Old thread, hopefully new spin on "allow" v.--"enable.
33. Re: The Real Offense
34. Re: on "CAN", was Old thread, hopefully new spin on "allow"
35. Re: Question for Contractors
36. Re: The Real Offense
37. RoboHELP as a single sourcing tool
38. screwy crop marks
39. Cover design requested
40. Useful Lessons For New People
41. Re: Question for Contractors
42. RE: Clarification (was Real Offense) --now just really of...
43. another printing query
44. Re[2]: The Real Offense
45. Re: Blue Collar Tech Writers
46. Re[2]: The Real Offense
47. Re[2]: The Real Offense
48. RE: Massively Automated Intranet
49. Re: Question for Contractors
50. Re: Question for Contractors
51. SUMMARY: Writing Error Messages (Long)
52. terms: window/dialog
53. Re: Ideas in Motion
54. Re: Blue Collar Tech Writers
55. Documentation on the Web
56. RE: Documentation for Beta Users
57. OT: conferences
58. Re: The Real Offense
59. Quotes Around Messages?
60. RE: Question for Contractors
61. Am I employable?
62. Word 97 to PDF question
63. Word 97 to PDF question

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

Subject: Re: Updating foreign language translations
From: "Peter Ring, PRC" <prc -at- prc -dot- dk>
Date: Fri, 10 Mar 2000 12:13:44 +1
X-Message-Number: 1

Linda Hughes asked:

.

> However, six months to a year down the road, comes
> the new revision of the software. New features, altered features, improved
> algorithms, etc. Now we need to update the manuals not only in English, but
> in 10 other languages. There are new sections, new paragraphs, new
> sentences, sometimes only a few words in a sentence need to be altered.
>
> Has anyone out there found an efficient and cost-effective way to handle
> incremental updates? We are using two different translation services (with
> translation memory databases), with mixed results. If anyone has developed a
> formal procedure, I'd love to see it. Recommendations for translation
> services are welcome also (third-party only please, I am not soliciting
> spam).

The answer to your question is to use translators using a "Translation
Memory System", e.g. Trados, which I use. Here the translators only
needs to translate the changed texts + spend a little time on checking
the rest and calculate the number of characters/words/lines actually
translated. The translation can be made with a personal dictionary for
your preferred professional terms, controlled by you or by the
translator.

For further information, see e.g. the Trados website at
http://www.trados.com.

Neither I nor my company (PRC) are related to Trados except as a user
of their products.

If you are interested, I can do the translation into Danish.


Greetings from Denmark

Peter Ring
PRC (Peter Ring Consultants)
- specialists in user friendly manuals.
  prc -at- prc -dot- dk
- the "User Friendly Manuals" website with links, bibliography, list
  of prof. associations, and tips for technical writers:
  http://www.prc.dk/user-friendly-manuals/
- special software for technical writers:
  http://www.prc.dk/software/

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

Subject: Re: Ideas in motion
From: "Dan Roberts" <droberts63 -at- earthlink -dot- net>
Date: Fri, 10 Mar 2000 07:06:33 -0500
X-Message-Number: 2

I suspect that, as usual, both POV's are extreme and that the Truth lies
somewhere betwixt and between. Any effort to repair substandard
documentation must be viewed in terms of time, effort, and return.
Ultimately, this is not a now/never, either/or question, but one of degree.
In other words, how much Bang do you get for the Buck?

To use the example of adding 2 pts leading...IF it can be accomplished
quickly and easily, w/o impacting the schedule to any serious degree, and
can provide increased retrievability, go for it. If it will take days to
accomplish, the ROI might not be worth it.

But let's take a more substantive example: info mapping. If the existing
text is a blob of undifferentiated text, info mapping might provide greatly
improved retrievability, improved reader comprehension, and (possibly)
result in fewer calls to Customer Support. In which case, the question then
probably becomes one of whether there is room in the schedule to accomplish
info mapping (and the associated question of whether the extra time comes
from nudging out the schedule for the TW or from the TW burning some
midnight oil).

And if the TW will be with the project through a number of releases, the
issues become even more muddy. If release X can support only minor
improvement X, perhaps release Y will provide time to implement improvementt
Y, and release Z provides room to implement improvement Z.

OTOH, the rules for a contract TW might be completely different. Or might
not. Depends on the relationship between the contractor and the company.

-----Original Message-----
From: Andrew Plato <intrepid_es -at- yahoo -dot- com>


>--- "Hedley Finger (EPA)" <Hedley -dot- Finger -at- ericsson -dot- com -dot- au> wrote:
>> So, when your client's style guide violates every principle of
information
>> design and human psychology, it is your DUTY as a professional to point
it
>> out.
>> But you cannot simply high-handedly go ahead and implement change.  Point
>> out that the client's document comes a poor last to that of the
competitor.
>> Demonstrate the inadequacy or lack of informative running heads, Make a
business case:  my
>> recommendations save $$$$/year in time not lost in trying to locate
>> information.  My recommendations will save $$$$/year because FrameMaker
>> conditional docs enable many different product versions to be documented
in
>> a single file set.  Point out the drabness of the cover and layout
compared
>> to the gorgeousness of the Web site and the GUI.  Show that restructuring
>> the document will improve maintainability and reader accessibility.
Show
>> that adding 2 points of leading actually improves readability.
>
>There are times when you have to accept the
>environment as is and make do. Especially as a contractor.
>
>Many companies don't care about human psychology and the theory of color.
They
>want docs fast and cheap. They don't need a lecture in the latest
productivity
>fad and how the Rational Master Blaster Methodology will make them more
>productive. Sometimes the best solution is to just jam out the docs
>and streamline the process later.
>
>[P]roduction cycles are
>fast - especially in high tech. There isn't time to waste on showing the
>universe the exquisite wondrousness of leading or single-sourcing.
>
>Once again - I know it FEELS right to make business cases and show how
>FrameMaker is more valuable, etc. But this is still one-off from what you
>should be doing - writing the damn documents.




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

Subject: FW: Question on Professional development policy?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
Date: Fri, 10 Mar 2000 08:20:29 -0500
X-Message-Number: 3

Marc Santacroce wondered <<Does anyone's organization have a Professional
Growth Policy or Professional Growth Guidelines, for use when making
decisions about spending company money to pay for membership dues in
professional organizations or professional conference/seminar registration
fees?>>

FERIC will pay for one membership per employee without question (two
memberships if you're at a supervisory level), and an additional membership
if you can make a compelling case for it. We also have provincial guidelines
for the minimum % of our budget that we have to spend on training and
professional development, so it's usually easy to make a case for getting
training of various sorts. But some training is also given as a reward for
good performance: the better the work you do, the more likely they are to
let you fly off to attend a conference of some sort.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

Hofstadter's Law: The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Law.

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

Subject: Re: Ideas in Motion
From: "Tim Altom" <taltom -at- simplywritten -dot- com>
Date: Fri, 10 Mar 2000 08:43:54 -0500
X-Message-Number: 4

I think Andrew has touched on a point that is too often ignored in our
industry: some of us think of what we do as a profession, while others see
it as a job.

The difference is in the degree of responsibility. Some of us point to
doctors, lawyers, accountants, and other professionals who must stand behind
their work, no matter who they work for, and say we should at least show the
same responsibility even if we're not legally obligated to do so.

The other camp maintains that what we're doing is far, far away from those
professions, that what we do is what we're told to do. Take your check, cash
it, and move on.

I understand both points of view, and I see the business imperative that
Andrew writes about. Many high-tech companies want to pump out technology
and don't care if anybody can actually use it. They won't listen to a
professional communicator if one shows up. So from his perspective, Andrew
is correct.

My sorrow isn't that there are these two kinds of approaches and writers,
but that they have the same title and appearance. Clients, employers, and
even colleagues often can't tell the difference until it's too late.
Projects that deserve high-level professionalism receive shoddy treatment,
often because nobody else on the team could tell dross from gold until it's
been spun and the check cashed. In our city, there are large numbers of
clerical employees typing transcriptions for a Fortune 500 local company,
who, due to corporate politics, must be given the titles of "technical
writer". Other industries are busily splitting their expectations into
levels, and I expect ours will have to follow.

Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar Method(TM)
"Better communication is a service to mankind."
317.562.9298
Check our Web site for the upcoming Clustar class info
http://www.simplywritten.com

>
> No, sometimes it is NOT your duty to point out the faults. Tech writing is
NOT
> synonymous with medicine. There are times when you have to accept the
> environment as is and make do. Especially as a contractor.


Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar Method(TM)
"Better communication is a service to mankind."
317.562.9298
Check our Web site for the upcoming Clustar class info
http://www.simplywritten.com



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

Subject: Updating foreign language translations?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
Date: Fri, 10 Mar 2000 08:52:56 -0500
X-Message-Number: 5

Linda Hughes is having trouble with updating manuals to account for <<...the
new revision of the software. New features, altered features, improved
algorithms, etc. Now we need to update the manuals not only in English, but
in 10 other languages. There are new sections, new paragraphs, new
sentences, sometimes only a few words in a sentence need to be altered.>>

Part of this depends on the tools you're using. I recently did something
like this on a much smaller scale with two documents published in Word 97.
The (French) author made his revisions in the French version of the file
using revision tracking, then sent me the file. I opened the file, found and
edited his edits, then opened the English file beside it. I went through the
French file, one revision at a time (this is easy to do by opening the
"Accept/review revisions" dialog box, clicking "Find next revision", then
closing the dialog and editing on it; you can also use the "search" function
if that's easier for you), and made the same changes in the English. Then I
"accepted all" the revisions, and both versions of the manuscript were
suddenly in sync. I've heard of people using Word's "compare documents"
feature for similar tasks, but got the impression that it doesn't work as
efficiently or as reliably. I imagine Frame and most other modern word
processors have comparable features. If you and your translators have
compatible tools, then you should be able to use a combination of these
approaches to succeed. (And if you don't, you should find translators who
are willing to adopt your software; it will save lots of grief down the
road.)

If you don't have the same software, there are a variety of more primitive
but equally effective means of accomplishing the same end. You can certainly
prepare a separate document that is full of lines such as "on page 2, line
17, insert the word 'equal' at the beginning of the line; the result should
read...". You can also simply mark the changes on a printout of the
manuscript. For example, when someone inserts a last-minute correction in
one of our already-edited French manuscripts and a fine point of French
grammar is beyond my skills (which is often), I can highlight the change
(circle it in red ink) and fax the document to our translator. She can then
return the fax or call me and say "no problems" (well... "pas de probleme"
<g>). And yes, this is one of those frequent Homer Simpson moments for me...
it never occurred to me until I started thinking about your problem that,
now that our translator uses the same software we use, I can take my own
advice and send her the edited file! <g> D'oh! This is another of those
proofs that by helping others, you often help yourself. Thanks!

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

Hofstadter's Law: The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Law.

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

Subject: RE: Question on Professional development policy?
From: Kay Robart <kay -dot- robart -at- integratedconcepts -dot- com>
Date: Fri, 10 Mar 2000 08:08:03 -0600
X-Message-Number: 6

I don't know about a written policy, but most companies I've worked for have
paid for one professional membership and have allocated a per capita budget
for training. It is up to the individual to choose which professional
organization
to join, if any, and choosing how to spend the training budget is usually a
joint
decision with the manager. Some managers leave it up to the employee to
request permission to attend seminars and conferences, while others actively
suggest training. Not everyone usually takes training every year, but it is
up to them. What makes it fair is the equal budget for each employee.

Kay Robart


> "Does anyone's organization have a Professional Growth Policy or
> Professional Growth Guidelines, for use when making decisions about
> spending
> company money to pay for membership dues in professional organizations or
> professional conference/seminar registration fees? We are trying to
> develop
> some guidelines that would help our several managers allocate such
> expenses
> fairly and consistently."
>
> Thanks,
>
> Marc
>
>
>

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

Subject: RE: Ghost Writing/Publication Credit
From: Kay Robart <kay -dot- robart -at- integratedconcepts -dot- com>
Date: Fri, 10 Mar 2000 08:12:58 -0600
X-Message-Number: 7

I was not taking the term "ghost writing" literally. It depends upon
the agreement. I am thinking of a similar situation where I was asked
to put the SME's name as principal author of an article that he had
only reviewed (and made no comments on). I was not asked to take
my name off, but it was given second place. However, I have heard
of writers being asked to put ONLY the SME's name as the author. In
that case, I think it would be OK to include the article as a work sample
and explain the circumstances.

On the other hand, if you have made an agreement to "ghost write,"
and remain completely anonymous, yes, I think part of the deal is
that you do not get credit for the work. I can't imagine agreeing to
that unless I don't want to be associated with the work!



> I always thought that the very fact that something was "ghostwritten"
> implied
> that the ghost writer would not get credit for the work.  When you ghost
> something, you agree to "help" someone write and agree that their name
> gets put
> on it.
>
> Why then would you later want to take credit?  It seems to me to be a
> breach of
> faith.
>
> Marilynne
>
> At 12:14 PM 3/8/00 , you wrote:
> >Did you get your name on the byline, too? Was there a reason why not?
> >I think you should be able to take credit as long as you explain what
> >your contribution was.
> >
> >Kay Robart
> >
>

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

Subject: OT: need a computer
From: Kari G Andres <kandres -at- UDel -dot- Edu>
Date: Fri, 10 Mar 2000 09:31:46 -0500 (EST)
X-Message-Number: 8

sorry for the off-topic and the cross-posting, and hope this is ok.  i am
a mac person, and i need to purchase a pc ASAP.  i know a little bit
about what i want, but i'm just don't have the time to research all the
ins
and outs and any suggestions, recommendations, and advice would be greatly
appreciated.  pls respond off-list.

i just want something basic, with enough memory to have a couple of
applications open (forehelp, word, pagemaker), sound cards, with the
ability to upgrade, a color printer.  something my kids can use to play
their games.  i don't have a lot of money.  and this would basically be
the second computer. i do some work where i have trouble going from a pc
to a mac and vice-versa.

i know this is a basic question, but any advice would be greatly
appreciated.  thanks.

Kari Gulbrandsen
http://copland.udel.edu/~kandres/default.htm
http://www.thewritingden.com


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

Subject: A vs an
From: "Patricia Castin (Trish)" <pcastin -at- dset -dot- com>
Date: Fri, 10 Mar 2000 09:32:30 -0600
X-Message-Number: 9

I was wondering the exact same thing and was about to post when I saw
this.  Thanks for proving I'm not (totally) nuts!

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

Subject: RE: a vs. an
From: "Murrell, Thomas" <TMurrell -at- alldata -dot- net>
Date: Wed, 8 Mar 2000 15:38:10 -0500
X-Message-Number: 64

I'm wondering why no one has picked up on what seems to me to be much worse
than "a/an."

Wouldn't it be better if it were a(n) _historic_ moment?


Grumble, grumble, grumble
Trish Castin
Lead Technical Writer
DSET Corporation
908-526-7500 ext. 1333

"I shall endeavor to perform adequately" - Data


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

Subject: RE: The Real Offense
From: Arlen -dot- P -dot- Walker -at- jci -dot- com
Date: Fri, 10 Mar 2000 08:56:03 -0600
X-Message-Number: 10


>The real offense is pompous pontificators who think any idiot who bothers
to
>learn the technology can write about it.

The same, of course can be said of the buffoons who believe that any idiot
who can write can write intelligently about a technology.

Sorry, I'm on Andrew's side in this brouhaha (in light of which startling
revelation Andrew is now rethinking his position). I've been victimized too
many times by manuals written by someone who obviously had no real
familiarity with the product or its use in the real world.

It takes *both* a knowledge of the technology and an ability to write to
produce useful docs. One or the other is not sufficient. Either can be
acquired by interested parties; all too many apparently lack that interest.


Have fun,
Arlen
Chief Managing Director In Charge, Department of Redundancy Department
DNRC 224

Arlen -dot- P -dot- Walker -at- JCI -dot- Com
----------------------------------------------
In God we trust; all others must provide data.
----------------------------------------------
Opinions expressed are mine and mine alone.
If JCI had an opinion on this, they'd hire someone else to deliver it.


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

Subject: Re: Old thread, hopefully new spin on "allow" v. "enable.
From: Harry Hager <hhager -at- dttus -dot- com>
Date: 10 Mar 2000 09:07:59 -0600
X-Message-Number: 11


     Listers,

     "USE"

     I've been reading this thread for a few days and I want to go off in a
     tangent and add something that has not been mentioned: the use of
     "use" as the action verb in technical writing.

     I consider "use" to be a very weak action verb and I try to avoid it.
     It's an all purpose action verb that we use when we don't think about
     the real action that is taking place. The reader can usually figure
     out what we mean when we say "use" but I don't like to take that
     chance. I try to be precise about the action taking place.

     Examples:
     - You use the xxx command to xxx.
     - You use the xxx window to xxx.
     - You use the xxx program xxx.
     - You use the xxx button to xxx.
     - You use the xxx checkbox to xxx.

     I prefer the following:
     - You select the xxx command to xxx.
     - You open the xxx window to xxx.
     - You start the xxx program to xxx.
     - You click the xxx button to xxx.
     - You select the xxx checkbox to xxx.

     You get the idea by now.

     "LET"

     In this context, I also prefer using "let" instead of allow or enable
     because let is more informal and has a more casual tone and a less
     controlling (allow) or a less techie (enable) tone to it.

     I may be getting in deeper that I can defend, but if allow is okay,
     then why not permit? The point is that allow is a very close synonym
     to permit. However, let, while a synonym to both, has a more informal
     and less threatening and controlling tone than allow or permit.

     I try to avoid enable in most user documentation. Enable is a techie
     term and is new to the scene (relative to let). There are many users
     who don't have the foggiest idea what it means. (And might even be
     confused by all the psychobabble in the current media about enablers,
     enabling, etc.) If your target audience consists of techies, enable is
     fine.

     I also like let because while the user needs to feel in control, the
     user can only do what the program is designed to do, nothing more. Let
     helps identify to the user where the boundaries are for the program
     (window, command, etc.).

     "CAN"

     One more thought: I do not use the word "can" anywhere in my
     documentation, as in "You can select the xxx command to xxx, You can
     click the xxx button to xxx." In these cases "can" is not needed and
     really adds nothing to the sentence, it's just an extra word. You do
     not change the meaning of these examples if you eliminate "can."

     H. Jim Hager
     hhager -at- dttus -dot- com


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

Subject: Re: Curious printing problem (PRN files)
From: "Chris Jackson" <crassick -at- bellsouth -dot- net>
Date: Fri, 10 Mar 2000 09:26:49 -0500
X-Message-Number: 12


A year ago, I had a hell of a time taking a 250-page Word 98 file into PDF
because of tables. The PDF file would not print correctly on a HP printer
(4si, I believe). I spent days and days on this, working with Adobe and MS
support. The only thing that worked was to replace all of my custom tables
with autoformat tables. The custom tables weren't anything complex, just
thinner gridlines. I believe the problem is Word's inability to to handle
complex docs (I don't mean to resurrect one of those threads!). There's a
lot on this for both Mac and Win Word in the www.MacFixIt.com forums (search
for "Word 98" and read the "Word 98" thread). I'd say that if your gray is
not part of the autoformat, turn the tables to autoformat and see if that
helps.

I'd be curious to hear what you find out, considering that I've had more
problems with tables corrupting files in Word just recently. And I can't
wait to dump Word if and when we go to XML.

Chris Jackson


----------
>From: Sybille Sterk <sybille -at- wowfabgroovy -dot- net>
>To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
>Cc: WINHLP-L -at- ADMIN -dot- HUMBERC -dot- ON -dot- CA
>Subject: Curious printing problem (PRN files)
>Date: Thu, Mar 9, 2000, 6:50 PM
>

>Dear All,
>
>I've got a very strange printing problem. To get our files ready for
>professional printing I create PRN files from Word. I've had quite a few
>problems in the past, but this is just too much! We are using tables for
>notes where the area for the text is shaded with a light grey.

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

Subject: RE: punctuation and procedure titles...
From: "Christensen, Kent" <lkchris -at- sandia -dot- gov>
Date: Fri, 10 Mar 2000 08:27:52 -0700
X-Message-Number: 13

re:  colons in them

Tom Murrell correctly, I believe, pompously pontificates "How you punctuate
your lists is a choice you get to make as a writer."  He additionally, again
correctly in my view, urges consistency.  My contribution to this discussion
is that in technical writing--the ostensible subject here rather than
college, English lit, or other manifestations of the unreal world--I'm in
the camp "less is more."  Colons in procedure titles are just noise, easily
and usefully omitted.  They're consuming some of your valuable white space,
and I say choose to conserve white space. Consistently.  Sans serif font,
too.


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

Subject: Re:  Clarification (was Real Offense)
From: "Michelle Wolfe" <WOLFEM -at- bcbsil -dot- com>
Date: Fri, 10 Mar 2000 09:42:04 -0600
X-Message-Number: 14

David Downing wrote:

<<The end user doesn't need or want to know about such things as file  =
<<structures, parameters types, function calls, etc., etc.  The end user =
<<wants to know "How do I use this program to do my resume/term <<paper, =
etc."

That all depends on who your end user is!  Not all of us write documentatio=
n for word processing programs ;-)  Some of us write technical documentatio=
n for how to use new programming languages, databases, or network software =
that require the user to understand file structures, parameter types, =
function calls, etc.=20

IMHO I guess what it boils down to is that some of us are better prepared =
to write to the highly technical audiences than others. It is what makes =
us stand out in the technical writing field and keeps our customers coming =
back to us.

Michelle Wolfe
Training Consultant


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

Subject: RE: Ideas in Motion
From: Emru Townsend <etownsen -at- Softimage -dot- com>
Date: Fri, 10 Mar 2000 10:50:34 -0500
X-Message-Number: 15

So far as I'm concerned, technical writing's essential rules are the same as
writing for a magazine, newspaper, or other publication:

1) Do your best.
2) The editor/boss is always right.
3) Know your audience and write to them.
4) If you think you know a better way, diplomatically discuss it with your
editor/boss.  If at the end your editor/boss disagrees, refer to rule 2.

These rules are in order of importance.  All other rules come after.  Is
that so hard?

Emru Townsend, Information Developer | etownsen -at- softimage -dot- com
Softimage, Inc.
Personal page: http://purpleplanetmedia.com
Recent musings: http://www.montreal.com/tech/2000/03/03lazy.html

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

Subject: RE: A vs an
From: =?iso-8859-1?Q?Aoid=ECn_Scully?= <ascully -at- flexicom -dot- com>
Date: Fri, 10 Mar 2000 15:57:24 -0000
X-Message-Number: 16

I've always thought that 'a(n) historical moment' and 'a(n) historic
moment' meant two different things.

'Historical' means 'a moment from history'...and 'historic' means 'a
history-making moment'...


Hmmm...maybe I'm wrong...there's a first time for everything, I suppose.
:)

-----Original Message-----
From: Patricia Castin (Trish) [mailto:pcastin -at- dset -dot- com]
Sent: Friday, March 10, 2000 3:33 PM
To: TECHWR-L
Subject: A vs an


I was wondering the exact same thing and was about to post when I saw
this.  Thanks for proving I'm not (totally) nuts!

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

Subject: RE: a vs. an
From: "Murrell, Thomas" <TMurrell -at- alldata -dot- net>
Date: Wed, 8 Mar 2000 15:38:10 -0500
X-Message-Number: 64

I'm wondering why no one has picked up on what seems to me to be much
worse
than "a/an."

Wouldn't it be better if it were a(n) _historic_ moment?


Grumble, grumble, grumble
Trish Castin
Lead Technical Writer
DSET Corporation
908-526-7500 ext. 1333

"I shall endeavor to perform adequately" - Data


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sponsored by Weisner Associates Inc., Online Information Services
Training & consulting for RoboHELP, Dreamweaver, HTML, and HTML-Based
Help.
More info at http://www.weisner.com/train/ or
mailto:training -at- weisner -dot- com -dot- 

Your web site in 32 languages? Maybe not now, but sooner than you think.
Contact ForeignExchange for the FREE paper, "3 steps to successful
translation management" (http://www.fxtrans.com/3steps.html?tw).

---
You are currently subscribed to techwr-l as: ascully -at- FLEXICOM -dot- COM
To unsubscribe send a blank email to
leave-techwr-l-9688H -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.

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

Subject: RE: Web help tools - review
From: William Swallow <William -dot- Swallow -at- aptissoftware -dot- com>
Date: Thu, 9 Mar 2000 14:47:13 -0500
X-Message-Number: 17

<snip>
I've been assigned to document all our systems and products and publish the
documents on our intranet. These documents will be a combination of
reference material, How-to and policy/procedure. It's a huge assignment
which I can do manually but I'd like to know how others have used the
available HATs (HTML Help, WebHelp, Forehelp Pro, etc.) to perform a similar
task. A breakdown of PROs and CONs would be appreciated. I'll publish the
summary of all responses back to the list.
</snip>

Uh huh. I could tell you all about everything I do and use to do this and it
may or may not help you at all. You failed to mention a few key ingredients
to narrow your responses down to something useful:

1) What tools you use/know how to use

2) What the docs are currently written in

3) What sort of timeframe you have to work with

4) What kind of docs you're working with

Anyhoo... what you were looking for... Here's the skinny on what we do:

We write technical end-user documentation for telecom billing and rating
software. Our books are big and there are lots of them. We write in
FrameMaker because in our opinion it's the most efficient tool for this type
of work. When we publish to the Web, we use Adobe Acrobat to bang out PDFs
for the print-friendly pulpit and use WebWorks Publisher for the
online-means-online pulpit. By sticking to rigid templates and style across
the board, we're able to single-source all of our documentation in a timely
and painless manner.

Sure, we looked into many tools. We decided against RoboHelp, Doc-to-Help
and other Word-based HATs because... well... we don't use Word (and the
whole save-as-RTF-from-Frame thing is a big headache that we would rather do
without). We decided against ForeHelp because it couldn't import MIF. Now it
can, but from what I've heard from others, it's not as slick a solution as
other Frame-based tools.

When we're not single-sourcing, AND when we're working for the Web only, we
use Dreamweaver (not just because it has a really cool name... else we would
have chosen Cold Fusion). DW is a great Web building tool and it's fairly
easy on the wallet (under $400.00).


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

Subject: RE: Updating foreign language translations
From: Andrew Becraft <AndrewB -at- ACCINT -dot- COM>
Date: Fri, 10 Mar 2000 10:34:59 -0500
X-Message-Number: 18

Peter is absolutely correct, Linda.

If your company is updating content on a regular basis, your *only*
cost-effective option is to choose a localization vendor that uses
translation memory tools.  The revision control features of applications
such as MS Word and Framemaker are limited at best, and produce often
inaccurate and unreliable results.  Currently, the industry standard in TM
formats is Trados -- a German/Irish company that develops tools such as
Translator's Workbench (their translation interface), S-Tagger (an
application for processing Framemaker and other DTP formats files through
TM), and WinAlign (a tool used to convert existing translations into TM that
you can leverage into your new documentation).

Even if you've already launched your localization project, it's not too late
to take the translation memory road.  As I mentioned above, you can use
WinAlign to pair your existing English and translated content, and export
that to a format you can use to leverage into any new content.  However,
aligning can be cost-prohibitive in the short run, and if you haven't
started translation yet you should immediately look into having your vendor
use a TM tool.  If your current vendor does not use and is not able to start
using translation memory, you may want to seriously think about switching to
another localization company.

One drawback of TM tools is that you will have a semi-fixed production/file
management cost associated with your projects every time you have an update,
mainly because of the way TM tools apply translated segments to the source
language files.  This means that you or your vendor will have to verify the
layout of your files every time there is a change, no matter how small, if
you want to keep your TM databases up to date.  Write me if you'd like some
suggestions on keeping your production costs down while keeping your content
in line with the English. (Just so you know, I'm not currently affiliated
with any localization company -- including Trados -- and have no business
interest in convincing you to use TM.)

As Peter said, check out http:/www.trados.com for a list of companies that
use their tools.

Best,

Andrew Becraft
Technical Writer
(formerly Publishing Team Lead at International
Communications/INT'L.com/LionBridge)

-----Original Message-----
From: Peter Ring, PRC [mailto:prc -at- prc -dot- dk]
Sent: Friday, March 10, 2000 7:14 AM
To: TECHWR-L
Cc: Linda Hughes
Subject: Re: Updating foreign language translations


Linda Hughes asked: