Asking for help . . . LOTS

[turnleftatnowhere -at- yahoo -dot- com]

This is about doing API documentation. Everything I've read on this list
seems to indicate that the process of documenting an API is hellishly
complex and only the very best alpha geeks of the documentation world can
manage it. Late yesterday afternoon the VP gave me the job of documenting
the API for my company's product. He and I are supposed to discuss the
project this afternoon.

I'm the only tech writer in a software company that has more than two
dozen developers/engineers. They've been in business more than four years
and never had a tech writer until I was hired - the developers did all the
documentation. Our customers are government agencies and the product deals
with transferring large sums of money. The only API information available
right now is in the form of notes and brief skeleton documents on the PCs
of individual developers. The product is Java-based and there are
something like 400 JSP files (estimated-nobody has ever done a count). The
developers admit the internal commenting in the code is way behind, and
nobody has ever counted the lines of code. The VP wants the documentation
finished by the end of this year. He wants me to use JavaDocs, which he
apparently knows. He also wants me to "police" the code commenting by
using the bug tracking system to point the developers toward places where
comments are missing or out of date.

At the same time as I work on this, there are development projects that
require user manuals, functional design documents, and report format
manuals. I've never used JavaDocs before. I've never had one minute of
formal training in Java, or in programming in any language. My only
software knowledge comes from OJT, reading books on my own time, tutorials
available over the web, and picking up things from working with
programmers over the years. I'm not part of the developers' chain of
command and we don't work for the same boss - they're in the product
development department and I'm in the customer engineering department.
Developer access will be limited. Some of the developers are trying to fix
a system that just went live (it's having lots of problems and the
customer is having fits), and others are working on a new project that is
supposed to go live next April (and the development process is already two
months behind schedule). The vast majority of my experience has been with
user manuals and online help systems. I've never before dealt with an API
or an SDK or anything of that sort. I've never even seen API documentation
before now.

(I may not have been given the most ******-up assignment ever handed a
tech writer, but I think I can make a strong argument to support a claim
to that title.)

Can anyone point out one or more Web sites and/or commercially available
books that can tell me everything I need to know about documenting an API,
and/or about using JavaDocs? In considering this question, please remember
I'm 100% totally ignorant. I need something that will do the moral
equivalent of taking me by the hand and walking me through every step in
the process. I've downloaded the Sun SDK that includes JavaDocs, but so
far I haven't had the time to check it to any depth, and I haven't found
any instructions on actually *using* JavaDocs. Please don't refer me to
any mailing list archives - I've already gone through the archive of this
site and gotten all the good out of it that I can, and I don't have time
to comb through God knows how many email messages to see if they contain
something I can use.

Any help would be greatly appreciated. Please don't bother to offer
condolences, and especially don't tell me if you consider the task
hopeless and my job as good as lost - I can think that for myself.

Thanks. I hope things are going well for all of you.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.