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.
Vlad Dracul wonders: <<My employer wants to prepare a developer's guide for
a base product of a suite of middleware products. The argument being offered
in favor of preparing such a document is that the readers would be hard-core
developers
who would use the base product to develop software. But, would not such a
document merely be a user guide for an audience that comprises developers?>>
Any guide that tells you _how to use something_ could certainly be called a
"user's guide". But the advantage of changing the name is that it provides
more precision: a developer's guide is a user's guide for developers, an
administrator's guide is a user's guide for administrators, and so on. How
do you distinguish these guides from the guide for the users of the
software? By choosing a different and more specific adjective.
<<If a user guide for developers should be called a developer's guide, then,
in what way would the developer's guide differ from other user guides?>>
It would focus on the needs of the developer rather than of those who use
what that person develops. If I open the developer's guide, I want to know
how to use procedure calls, dimension variables, and allocate RAM. If I open
the user's guide and see any of this information, I'll run screaming. <g>
See the difference?
<<What is the focus of a developer's guide? What does a developer's guide
typically contain?>>
The guide should provide all the knowledge a developer needs to produce a
functional and efficient application. As a result, it typically contains an
overview of the software architecture (how everything fits together, perhaps
how the software differs from other similar software), a complete reference
guide to the commands (see our previous discussions of documenting APIs for
details), and perhaps even a list of tools and utilities to help get the job
done faster.
--Geoff Hart, ghart@ videotron.ca
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
RoboHelp for FrameMaker is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to online Help, intranet, and Web.
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! Call 800-718-4407 for
competitive pricing or download a trial at: http://www.ehelp.com/techwr-l4
---
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.
