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

Subject: Designing a new help system -- Oh boy! ...ugh
From: "Rene Stephenson" <RStephenson -at- mwci -dot- mea -dot- com>
To: techwr-l
Date: Thu, 2 Dec 1999 06:56:36 -0800

My Esteemed Colleagues....

I'm designing a help system for our newest platform-independent network
(coded in Java). I can only use JavaHelp (WebHelp, etc., doesn't play well
with Java-based programs), and since the network is still pre-1.0 ("one
point uh-oh"), the software is quite volatile. I am considering a few
issues ("opportunities") that could benefit from your insight.

1. Screen shots, good or evil -- Most screens are untitled, leaving the
documentation team to decide on terminology and creating some uncertainty
for the user (i.e., help says X screen should appear, but this screen
doesn't say if it's X or not). One solution would be to include popups of
screen shots, so that if the user isn't sure, they can get graphic
confirmation from help... the drawbacks being the expense of screen shots
-- overhead and time (money) to keep current with rapidly changing

2. Internationalization -- This software is presently only marketed in the
US, but plans are to go to Europe with it. (Our Japanese parent company
already has a similar product in the Asian markets.) So, it's likely that
the help system (if not the screens themselves) will need to be translated
into other Western languages at some point in the future, probably at least
2 years from now. What are some things I can do at this wonderfully early
stage to facilitate internationalization? I am familiar with certain
standards for internationalizing paper docs (avoid noun phrases, keep
subject/verb/object order and in close proximity, use proper grammar, avoid
jargon/colloquialisms/culturally-based analogies/humor). What else?
Anything special to consider for interantionalizing a *help* system?

3. Reviews -- What way(s) have you found successful for having JavaHelp
reviewed? In the past, I've created printed docs from the single-source
help files for SMEs to check technical content and editors to check the
writing itself, and then have a peer check links.

4. Project Schedule -- How can you possibly estimate the timeline for
creating a help system that works with software that's still being

I'd really appreciate your insight. If you think of other areas I should
consider, or issues I'm missing at this stage, please enlighten me!

Rene Stephenson
Technical Writing Consultant
Mitsubishi Telecommunications Network Division
(770) 717-6792

Previous by Author: RE: Export text out of PDF -- One-page-at-a-time limitation
Next by Author: SUMMARY: Designing a new help system
Previous by Thread: RE: WinHelp to HTML Help-Thanks to all...
Next by Thread: RE: Designing a new help system -- Oh boy! ...ugh

What this post helpful? Share it with friends and colleagues:

Sponsored Ads