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

Subject: RE: Designing a new help system -- Oh boy! ...ugh
From: "Giordano, Connie" <Connie -dot- Giordano -at- FMR -dot- COM>
To: "'Rene Stephenson'" <RStephenson -at- mwci -dot- mea -dot- com>, TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 2 Dec 1999 10:11:36 -0500


I can only address #4, the only way I've found to do an estimate is to look
at freeze dates and QA turnover dates as dependencies. Use any specs you
can find to determine the scope, and then look at these dates to determine
your milestones. For instance, I use a functional spec to determine the
number of topics I'll probably need, and I use the freeze date as the time
when GUI should stop changing. I use the QA turnover date as my start time,
and release from QA as my final date--that way QA and Documentation run more
in synch and we have a better shot of releasing accurate documentation with
the product.


Connie Giordano

-----Original Message-----
From: Rene Stephenson [mailto:RStephenson -at- mwci -dot- mea -dot- com]
Sent: Thursday, December 02, 1999 9:57 AM
Subject: Designing a new help system -- Oh boy! ...ugh

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

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

Sponsored by ForeignExchange (
Rely on ForeignExchange for responsive and professional
software localization and technical translation services.

You are currently subscribed to techwr-l as: connie -dot- giordano -at- fmr -dot- com
To unsubscribe send a blank email to leave-techwr-l-19883K -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: RE: Future XMLers (was document management and xml)
Next by Author: RE: Designing a new help system -- Oh boy! ...ugh
Previous by Thread: RE: Designing a new help system -- Oh boy! ...ugh
Next by Thread: RE: Designing a new help system -- Oh boy! ...ugh

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

Sponsored Ads

Sponsored Ads