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: API documentation and background information From:"walden miller" <wmiller -at- vidiom -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Mon, 25 Feb 2002 11:21:52 -0700
Steve asks two questions:
First, how much background information (that is,
outside the JavaDoc) do programmers prefer/need about
the actual application? ...
Second, ...have you had any success with presenting
it in a format that's more "approachable" than a
traditional, systemic presentation?
Walden:
In my experience, programmers don't write just a part of an application
without knowledge of the entire application.
One programmer may write a runtime engine, while another writes UI routines
that tie into the engine, etc.
PLUS, you never know what programmer will write which parts, so the process
of writing applications must be thoroughly documented. This may include
compile and test issues, in addition to the mundane code writing info.
Javadoc API docs rarely do more than skim the surface of what I would call
an application guide. I recommend more information than less.
As to your second question, I like to read about programming from an
informed perspective. Talk to programmers who used the API (or write an
application yourself to see what it takes) and interview them on application
skeletons, required code, typical gotcha's, etc. From your notes in talking
to engineers, you can build up an idea of what information is required.
>From the information quantity and type, you can develop a style that best
fits the data. (It is never a good idea to decide on a style before you
understand the limits and requirements of the data). The style doesn't have
to be traditional, but it does have to meet the needs and expectations of
your audience--engineers.
my .02
Walden
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now's a great time to buy RoboHelp! You'll get SnagIt screen capture
software and a $200 onsite training voucher FREE when you buy RoboHelp
Office or RoboHelp Enterprise. Hurry, this offer expires February 28, 2002. www.ehelp.com/techwr
---
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.
