Re: Punctuation and Hypertext

["Gallagher, Susan" <sgallagher -at- STARBASECORP -dot- COM>]

On whether there are more errors (or excuses for errors) in online docs,
Keith writes...

>I have been discussing this situation with many people recently. Just =
>last week, my copy of Arcada Backup for Win95 threw up an error message =
>which was a comma splice. I have recently heard people state that =
>on-line documentation does not go through the same editing process as =
>hard copy.

>Is that common? I agree that I wouldn't read a novel on-line, but give =
>me soft copy reference any day. I think more and more people are doing =
>this, too. With the growing importance of on-line docs, it seems to me =
>there should be great care and concern for their place in the editing =
>process. If there is a grammatical error in the help or in a dialog box, =
>does that mean there is carelessness in the code, also?

Whether online doc/online help is edited as well as its paper counterparts
is one question, whether error messages, status line help, and other
messages embedded in the code are edited at all is another question
entirely.

Usually, error messages, status line messages, and other messages embedded
in source code are in the programming domain. Whether they get edited at all
depends greatly on the organization, the staff, and how well integrated into
the development organization the documentation staff really is. I've been in
organizations where the writers had no control at all over the messages
embedded in source code -- and in the few organizations where I have become
involved in source-embedded messages, it has come about because I made it my
business to say sum'pin' about the large grey blob of alphanumeric garbage
at the top of each dialog box.  ;-) This is an area in which our involvement
is sadly lacking (IMnsHO).

Online help and online doc, however, are well within the writer's domain, so
theoretically, there's no excuse for sloppy work -- however...

To a large extent, the structure of the information is at fault. Editors who
are used to paper copy have (in *my* experience -- please don't misconstrue
 -- I'm not casting aspersions on all editors, by any means) a very difficult
time reading the "disjointed" help topic pages, ignoring (or making sense
of) the various footnotes and hyperlink jumps, and reconciling the changes
in writing style that online delivery demand. This was very true 4 years ago
when I first started creating help files -- I hope it's getting better, but
Idunno, I haven't had a real editor in a long time.

I've found that peer editing is much more effective in online doc creation.
Another help author is much more capable of grasping the sense of the thing
and catching the misdirected hyperlink, the cut-and-paste keywords gone
awry, and so on. If the 'peer' is an effective editor, so much the better --
if not -- <shrug> Oh, Well!

So, in summary, yes, I think there's a lot of room for improvement in the
editing of online messaging and in online doc/help. Online (source-embedded)
messaging will only improve when we tech writers (as a group) demand to get
involved in the total communication process of the software product. Online
doc/help files will improve when the editing staff 'catches up' to the
technology -- i.e., learns enough about hypertext creation to be able to
make sense of the files we give them to edit.

Does this mean there's sloppy code underneath the sloppy UI? Not
necessarily. Most programmers learn their programming language much better
than their mother-tongue.  ;-)

Just my $.02

****************************************************
Sue Gallagher
StarBase Corp, Irvine CA
sgallagher -at- starbasecorp -dot- com
****************************************************