Re: Intro to phases of creating API documentation

Subject: Re: Intro to phases of creating API documentation
From: Monica Cellio <cellio -at- pobox -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 8 Nov 2005 16:12:26 -0500 (EST)


> What are the tools I’ll need? (Java Doc, a version control system, an IDE)

You'll need Javadoc, and you'll need to be able to compile and edit the
source code. Ask for whatever software the developers are using for this.
You should always recompile the code after editing javadoc to make sure
you didn't, say, miss a close-comment marker somewhere, and it's in
everyone's best interests if you compile code the same way they do.
They're probably using ant targets or makefiles or IntelliJ configurations
to do that compilation, 'cause no developer wants to do more work than
he needs to do. :-)

> How many different kinds of docs are usually produced in an SDK kit? What is
> the main purpose of each?

Broadly, you'll have:
- an overview: what are the high-level pieces and concepts?
- developers' guides: for each functional area, how do you use it? This
is where you convey patterns of use and design principles; Javadoc gives
too detailed (and too unorganized) a view for that. Developers' guides
call out the typical uses and the important variations. Developers
refer to this when designing applications.
- documented examples: sometimes these are part of the developers' guides
and sometimes they're separate, but either way, it's important to show
actual code that uses the APIs. The distribution should include full
source code so customers can compile and run it.
- detailed API documentation: in your case, the Javadoc. Ideally, this
tells you everything you need to know about every package, class,
interface, and member. Developers refer to this frequently when writing
code.

> Anybody know of a good example of SDK documentation?

Java itself has good documentation.

> Orientation

In an ideal company, you'll be part of the development team and will
work with developers on a day-to-day basis, participating in code reviews
and using the APIs to write examples and test your understanding of the
API. If you are yourself a programmer, you already have some
understanding of your audience's needs; if you are not, discuss this
with your developers just as you would discuss the needs of any other
audience that you are not yourself part of.

> How common is it to have UML diagrams in an API doc? Is this generally
> created by the engineers? What tools do I need?

It's not uncommon. You'll need to talk with your developers to find out
if this makes sense in your project. Find out if there's a house style
or favored tool. These could be created by either developers or you.

> I have run JavaDoc - it magically pulls comments out of the code and formats
> them. What kind of information do I need to collect in order to populate
> those fields in the first place? 

This won't sound very helpful, but: everything someone would need to know
to use this class/member that isn't obvious from the signature.
Restrictions on parameters? Error conditions? Side effects?
Thread-safety considerations? Contents of returned Collections (because
you can't tell the object type from the signature)?

> Is ALL of the content stored in the code
> or are there pieces that I’ll have to add after JavaDoc runs?

You should not do any post-processing of the javadoc output, because
it would just be lost the next time you build it anyway. In addition
to the class-level documentation, javadoc supports package overviews
and an overview of the whole doc set. Your developers might not have
written these; if they haven't you'll want to. This is how you turn
a package containing 20 classes (which will show up alphabetically)
in an API containing 500 classes (again, alphabetical) into something
navigable.

Monica


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

Try WebWorks ePublisher Pro for Word today! Smooth migration of legacy
RoboHelp content into your new Help systems. EContent Magazine Decision-
maker review (October 2005) is here: http://www.webworks.com/techwr-l

Doc-To-Help 2005 converts RoboHelp files with one click. Author with Word or any HTML editor. Visit our site to see a conversion demo movie and learn more. http://www.componentone.com/TECHWRL/DocToHelp2005

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.



Follow-Ups:

References:
Intro to phases of creating API documentation: From: Anna Junglas

Previous by Author: native speakers
Next by Author: RE: documentation versioning and management software
Previous by Thread: Intro to phases of creating API documentation
Next by Thread: RE: Intro to phases of creating API documentation


What this post helpful? Share it with friends and colleagues:


Sponsored Ads