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.
Leanne Sanderson reports: <<I've been asked to create user documentation for
a client's existing custom application... with the understanding that they
will be moving from this stand-alone desktop application to a web
application in the next 18 months.>>
One of the first things you'll need to do is establish a "migration plan".
Work with the developers to find out what will change, and how, and figure
out how you'll cope with those changes with the minimal amount of pain. For
one thing, knowing how the software will be delivered (static HTML,
database-generated HTML, Java, etc.) will dictate your final choice of tools
and what approach to take to get from your current tools to the final ones.
For another, you can plan to address these changes in your writing right
from the start; to the extent it's possible, try to divorce the content from
the delivery medium (see our recent discussions of single-sourcing and Mark
Baker's insights regarding "normalization" for some good hints). Where
possible, write in such a way that you won't have to rewrite (or at least
not much) later.
<<One of the reason's they want to document the app now, is to get down on
paper everything the application does, to aid them in converting the
application to a web app. - which my company will also be doing.>>
This is a wonderful way to build good working relationships with the
developers. In effect, you'll be creating a specifications document that
they'll use to create the future product. Work with the developers to find
out what they want and need from this document, and build it for them.
They'll love you for this!
For the online portion of the documentation, consider some flavor of
HTML-based help. If you can get the help working well with the desktop
application, you can then migrate it fairly easily to the Web version. Of
course, that advice depends on what kind of product they plan to develop; if
it's a Java application, JavaHelp might be more appropriate, and you'll want
a tool that lets you transfer the desktop help file into the new format
simply.
--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
(try ghart -at- videotron -dot- ca if you get no response)
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"Work is of two kinds: first, altering the position of matter at or near the
earth's surface relative to other matter; second, telling other people to do
so. The first is unpleasant and ill-paid; the second is pleasant and highly
paid."--Bertrand Russell
NEED TO PUBLISH YOUR FRAMEMAKER CONTENT ONLINE?
?Mustang? (code name) is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to Web, intranets, and online Help.
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! See a live demo that
will take your breath away: http://www.ehelp.com/techwr-l3
---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -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.
