RE: Designing a new help system -- Oh boy! ...ugh

[Debbie Pesach <debbie_pesach -at- attune-networks -dot- com>]

Rene,

We are in a similar boat. But we've decided to go with ForeHelp's
InterHelp for our online help (OLH), that does play with Java quite
nicely. It took me about a month to finally decide (at the end of last
week) that we will pass over JavaHelp because it is so unstable and go
with InterHelp. We will consider JavaHelp only after it gets a bit more
functionality and our Java app stops using JDK 1.1.8.  I am lucky to
have a very detailed design spec, a wonderful crew who asks me to help
them before I offer my help and who actually read and comment on my
documents in detail. Sorry, I didn't mean to brag, but it is so
refreshing.

As to your specific questions (you didn't specify how
skilled/experienced your users are, so I may be making some incorrect
assumptions here, but I'm basing my comments on users who are not
overwhelmingly computer experienced--an "average" user?):

#1- I agree with those who say that you should work for accurate names
for your interface elements and, as much as possible, try to avoid
inclusion of screen shots in the OLH. I think that some usability
studies have also shown that this can be somewhat confusing and not very
helpful to users. Just make sure that you can roadmap as well as
possible--letting users know where they are and how to get there in the
body of the help. You are correct to say that the screen shots can be
very time consuming, and why waste your time that could be much better
spent on other things.

#2- My approach to internalization needs is basically parallel to my
approach to documentation in general. KISS (keep it simple
stupid/silly/Sam/Simon)! Avoiding humor, slang, & colloquialisms is
almost always a good idea. Try to avoid using words like  THAT/THIS/THEY
and instead specify exactly what you are talking about. This makes
things much easier for the translator.
BAD:
You can create or modify colors by using the Adjust button.  They are
easy to control this way.
GOOD:
You can create or modify colors by using the Adjust button.  The colors
are easy to control using this function.

If your programmers use text bundles (I just learned about these in
Java) you will have an easier time passing on text messages/error
message to the translator.

#3- My approach to reviews is multi-level. I tend to print out content
at the topic level to have the appropriate SME (subject-matter
expert)check for technical accuracy and sign-off on the topic. This is
in addition to providing the SME with versions of the OLH as they are
compiled.
The official link-checking is accomplished by myself (with the help of
ForeHelp's link checker) and by either the QA (quality assurance) person
or one of the SME's (I told you they were special)

#4- Schedule? That is a tough one (and probably quite a common issue). I
think you've received good answers from others about this. I'll add that
you need to keep a detailed record of what you do each day for this
project so that you can, at least as a summary at the end, get a sense
of how long things took you and where you got held up. This may not help
for now, but will be a big help for future projects.

Good luck!!


Debbie Pesach
Technical Publications Team Leader
debbie_pesach -at- attune-networks -dot- com
Tel:  972-4-9594333 Ext. 227
Fax: 972-4-9594332

Attune  Networks Ltd.
P.O. Box 305 
Yokneam Illit  20692  
Israel