Re: Asking for help . . . LOTS

[Goober Writer <gooberwriter -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. 

No. You just need to understand the differences
between how an API reference is written and used as
opposed to user documentation.

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

Makes sense.

> At the same time as I work on this, there are
> development projects that
> require user manuals, functional design documents,
> and report format manuals. 

There will *always* be other projects... ;)

> I've never used JavaDocs before. 

Ask a lead developer for an hour of time to go over it
- it's not that complicated.

> I've never had one minute of
> formal training in Java, or in programming in any
> language. 

You shouldn't need it. It helps, but it's not
required. You're not writing code. You're ensuring the
documentation comments make sense.

> Developer access will be limited. 

You shouldn't need a lot of access give you'll be
spinning through the code comments and bugging stuff
that really doesn't make sense. You should see if you
can get read/write access to the code base so you can
clean up code comments you know or feel comfy fixing
(typos and such).

> The vast majority of my experience has been with
> user manuals and online help systems. 

Nice! Way to broaden your experience!

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

Sure you have. You probably just didn't realize it.
Ever go digging into the VB reference for creating
Word macros? Or the documentation for WWP? Ever look
up something regarding RTF notation?

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

Huh?

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

http://groups.yahoo.com/group/xml-doc

> In considering this question, please remember
> I'm 100% totally ignorant. 

I'd disagree, and you might too once you realize what
you need to do. ;)

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

Sheesh. Talk about accepting an assignment with an
open mind...

=====
Goober Writer
(because life is too short to be inept)

"As soon as you hear the phrase "studies show",
immediately put a hand on your wallet and cover your groin."
      -- Geoff Hart

__________________________________
Do you Yahoo!?
The New Yahoo! Shopping - with improved product search
http://shopping.yahoo.com

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

ROBOHELP FOR FRAMEMAKER TRIAL NOW AVAILABLE!

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.