Language check list?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Radwa Darwish wonders about <<... a task I have been assigned to, it
involves a check list of most frequent errors our programmers
unintentionally leave in screen text, I have been editing screen text myself
and there has been a lot, I can list them all and their corrections as
examples, but I think it would be offensive and disorganized, most errors
include spacing, punctuation marks, typos and abbreviations... I just want
to present a well sorted check list and I need the guide lines...>>

The problem with the checklist is that nobody will use it. Most programmers
are more interested in getting the program working than in learning how to
write good error messages, and few programmers have the time to compare
their writing with a checklist to make sure they're following your
standards; even fewer have the editorial skills needed to do this work
reliably. Here's a compromise solution that will save you time and get
better results:

Convince the programmers to let _you_ write the error messages, or at least
to let you edit the messages before they're incorporated in the user
interface. The first case assumes that they have the time to sit down with
you, explain a problem, and work with you to come up with a good solution;
it's an ideal way to work, but not one you can always do because of time
constraints. (Some programmers who have particular problems with writing do
like it because it's faster than if they had to write the message
themselves.)

The second case is much easier: the programmers either e-mail you the
message so you can edit it and return it via e-mail, or they give you a file
(in Delphi, it's called the "language" file according to my pet programmers,
and there are surely equivalents for other languages) that you can edit
directly in a text editor. Usually, this also lets you edit user-interface
terms at the same time (menu names, field labels, etc.).

One caution: if you're editing a language file, make sure that:
- you understand the symbols being used by the programming language (e.g.,
sometimes ' or " or & are used to denote line breaks or as the prefixes of
special symbols; sometimes ";" marks a line break rather than being part of
a sentence). Don't edit these symbols unless you really understand how
they're being used.
- you query anything that you're not certain about rather than risking
introducing a significant error by correcting something that's not actually
an error.

One problem: examining the language file by itself removes all context, so
you can't see where the text comes from and what it's trying to describe.
Again, edit carefully. When in doubt, open the software you're documenting
and print a screen capture so you can hand-write the correction on that; the
programmers can then help you find the appropriate part of the language file
in which to correct the text.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

“Any sufficiently advanced technology is indistinguishable from a
personality, and an obnoxious one at that."—Kim Roper 

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.