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.
Peter Neilson wrote (in reply to turnleft's cry for help
about API docs):
+++
You should make yourself a list of all the API calls, each one with the
data types it takes as arguments and that it returns. It's possible
to get your Java IDE to produce this list for you. The number of them
will give you an idea of the scope of the project. Someone else on this
list may have an idea of how much time you'll expect to spend on each
one.
+++
I once knocked out 20 API reference pages in a day, but they were
for functions I knew well (I wrote some of them) and I'm afraid
some of the text may even have been of the "Increment(int x) --
increments an integer called x" variety Peter warns of :-)
(i.e., they were fairly simple functions where there wasn't
all that much to say, hardly any caveats / exposition needed).
Also I had RSI at the end of the day and didn't speak to anyone
all day, just bashed 'em in (after a week I'd done around 60 or 70).
If you need to factor in time to work out what things are,
read specs, read code comments, read code, or speak to developers
in order to find out what any given func is meant to do (never
mind how they fit into the bigger picture) then 10 a day would
be a very good rate (unless they are _very_ simple).
My biggest tip on providing API documentation is to include
an example code snippet which shows how to use a given
function / data type / control. This is the bit that most
programmers will really want to see when they look up a reference
for a function.
The other thing to consider is that a list of reference pages
for all the API functions is not the only thing you should
produce; you really need some more task-oriented docs as well
just as for any other type of documentation (i.e., how to use
the APIs to achieve a given task).
turnleft - you may not be in a position to produce all this
stuff straight away (sounds like you aren't). The best thing
you can do, IMHO, is to work closely with the developers to
ensure they produce something useful - they really are the
best people to do it, but you should help / cajole them to
produce something better than they would do on their own.
HTH, Chris.
Christopher Gooch, Technical Author
LightWork Design, Sheffield, UK.
www.lightworkdesign.com
HAVE YOU SEEN THE LATEST FRAMEMAKER PUBLISHING TOOL?
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 view a live demo at: 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.
