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.
VINAY BABU reports: <<The kind of work we do here is software development
for consumption within the organisation. We develop reusable software
components that can be integrated into larger system that forms a part of
the final product... in my environment, users of the software are actually
system integrators who are all technical people having a fairly decent
understanding of the software component in question. So the software cannot
be accompanied by a user manual that is typical of an end-user product. The
document however should talk about the features, paramaters and variables,
interfaces, the working and how the component gets integrated into the whole
system. Should such a document be called an integration document? Can anyone
tell me how to create an integration document and the format to be followed
in creating the same? What are the essential elements that needs to go into
such a document?>>
"Integration" document sounds perfectly reasonable, and your preliminary
sketch of what should be included (e.g., interfaces) also sounds good. But
here's the problem: _we're_ not the people you're writing for. Since you're
writing for colleagues in the same company, there should be few barriers to
contacting them and getting direct feedback on whether your plan will suit
_their_ needs. Do so. Come up with your best effort at understanding their
needs and providing documentation that meets those needs, then ask several
of your integrater colleagues to review them and ensure they work as well as
you hope they do. Revise your plan, resubmit it for testing (to be sure you
really understood their suggested revisions and solved any problems they
raised), then finalize the approach. Then get to work on the actual writing,
but don't forget to keep working with the integrators so you can improve
your approach as you go. They'll love you for making their lives easier!
--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"I vowed [that] if I complained about things more than three times, I had to
do something about it."--Jon Shear
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com
A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe. http://ieeepcs.org/2001/
---
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.
