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: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
Rene,
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.
HTH,
Connie Giordano
-----Original Message-----
From: Rene Stephenson [mailto:RStephenson -at- mwci -dot- mea -dot- com]
Sent: Thursday, December 02, 1999 9:57 AM
To: TECHWR-L
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
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!
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sponsored by Weisner Associates Inc., Online Information Services
Training & consulting for RoboHELP, Dreamweaver, HTML, and HTML-Based Help.
More info at http://www.weisner.com/train/ or mailto:training -at- weisner -dot- com -dot-
Sponsored by ForeignExchange (http://www.fxtrans.com/tw.htm)
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 http://www.raycomm.com/techwhirl/ for more resources and info.
