Re: Asking for help . . . LOTS

["Mike O." <obie1121 -at- yahoo -dot- com>]

turnleftatnowhere -at- yahoo -dot- com
> 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?

Wow, that post has to be the best, most coherent cry for help ever :-)

You don't need to buy a book, just go to the source:
http://java.sun.com/

Find examples of API docs here (these would be the canonical examples):
http://java.sun.com/api/index.html

Java developers expect their API docs done by Javadoc:
http://java.sun.com/j2se/javadoc/

Read this for Java background:
http://developer.java.sun.com/developer/onlineTraining/new2java/

Then create a Hello World java application:
http://developer.java.sun.com/developer/onlineTraining/new2java/programming/
learn/
and then document it with javadoc.

If you still aren't getting the hang of java, try to find a friendly
developer and get some one-on-one tutor time.

Then go get a more complex java app, and document it with javadoc.

Then go get some of your company's code, and document it with javadoc.

Once you run javadoc against your full codebase, you'll have an outline of
your API docs, and you will clearly see where comments need to be added.

Try the API writers group, lots of smart people over there:
http://groups.yahoo.com/group/nettechwriters/

> 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.

In some ways API docs are just like any other user guide. Identify your
audience and find out what they want and how they want it. Then give it to
them. If that process leads you into more "technical" territory, so be it -
just keep going.

Good luck, write again soon!

Mike O.




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

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.