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: Starting an API Doc Project From:"Bill Albing" <billa -at- fpoint -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Fri, 7 Nov 2003 08:31:28 -0500
Is developing an API doc any different from other doc projects? -- know
your audience (in this case programmers), know your product (don't be afraid
to actually run the software and see how it works), figure out what
information is needed, know your subject matter experts (in this case the
developers creating the software, set up some style guidelines for yourself,
etc.?
An API Doc project could involve more automation than other doc projects. I
certainly am not going to write 9,000 pages of reference for an
object-oriented application if a tool can produce it in minutes. So find the
automatic-generation tool that works best on your platform for what you want
to produce, if your software will work with one. Remember that no tool does
it all and that a human is involved in customizing the tool, editing the
output from the tool, and filling in where to tool leaves off.
Have access to the source code, if only to check the logic if the developers
don't have time for all your questions. Have access to the source code and
be able to edit the comments if the comments are used with the
automatic-generation tool to create part of the doc.
Get to know your developers -- find out who knows what, and who is willing
to talk about what, and what it takes to get them to review what you create.
Learn the conventions for your platform and market. Java API docs are going
to look different than Microsoft .NET API docs. Set up some style
conventions for yourself where those conventions leave off.
Hope this helps.
--------------------------------------------------------------
Bill Albing
FarPoint Technologies, Inc.
Technical Documentation
808 Aviation Parkway, Suite 1300
Morrisville, NC 27560 http://www.fpoint.com
(919) 460-4551 x106 mailto:billa -at- fpoint -dot- com
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.
