TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
screens.
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
developed???
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!
