Re: Help API Documentation?

[Chris Gooch <Chris -at- lightwork -dot- co -dot- uk>]

Ericka asked about API documentation, to which she is new,
and Glenn and Walden have have engaged in some religious-type
discussion of the pros and cons of using tools that convert
code comments into something that may or may not be a
starting point or maybe the finished docs if the Tech Writer
is allowed to alter the comments.

There's been discussion before of API documentation, and
tools, the fact that, in addition to the plain "man pages" for
each API function (or class or whatever), there also needs to
be a more descriptive layer to the documentation, as well
as tutorials etc.

However I think there's a good point being brought out by
Glenn and Walden's discussion, which is this; with API
documentation, it is important (vital even?) that the
software **developers see the production of the man pages**
for API functions (I'll say functions even though classes and
data types etc. may also be required) **as part of their job**.
The question is how to ensure this.

Glenn argues that using tools to "publish" source code
comments is an effective way of doing so. I believe he is right.

Walden argues that it is dangerous to allow stuff written
by developers go straight to customers. I believe he is also
right.

So, between the tech writer and the developers, it is important
to ensure that;

a) the developers edit the appropriate man page information
	whenever they alter the public interface to an API
b) the tech writer has the opportunity to edit what the developer
	has written before it is released to the world.

You can solve this by either;

i) keeping the man pages in the source code, in which case
	the tech writer needs to be able to alter comments direct
	in the code (otherwise the edits they make need making
	*every* time the docs are release, ouch)
ii) keeping the man pages in a seperate place, in which case
	developers need to know that it is their job to alter/create
	such pages and inform the tech writer when they do so.

There are pros and cons again to both, and which is best may
depend on the type of product, the type of development team,
the adherence or otherwise to code freezes, and so on. You may also
like to consider whether you want to publish the whole of your
API, or just the "official" bit.

These are essentially management issues rather than technical
ones. The trick is to ensure that joint ownership of reference type
material for APIs lies with the developers and the tech writer,
and their are various ways of doing so. The most important thing
is to get the working relationship right, and to ensure from day one
that everyone understands their responsibilities. 

For what it's worth, here's what I do;

+	API man (reference) pages live in a seperate place to the code,
	but accessible to developers as well as myself. The same RCS
	system covers code and docs.

+	If a developer alters the public interface of the API, he or she
	must ensure that the man page is altered. If they alter a man
	page, they must tell me. (Even if they didn't tell me, I *could*
check..)

+	I keep a list of all "changed" man pages in the run up to each
release.
	I then basically perform a QA type job on them, and either edit/fix
up
	pages as appropriate, or even sling back for more work from the
developer
	if that's appropriate. I don't require them to do immensely pretty
	pictures or write the best prose ever however - just to get the info
down
	clearly, for me to tart up.

+	I ensure that only pages that have been QAd by me get published,
	and that all pages that need to be published have been QAd by me.

This isn't the only way we could work, but it seems to work for us (gee I
hope
there aren't any irate customers reading ;-) ).

As I say, the important point is to get the responsibilities you expect of
the
developers to be accepted by the development team - this may take some
time. Don't allow developers to shirk and say "I don't do docs" - if they do
then using documentation tools won't necessarily help as the attitude
will still be there.

This then leaves you with enough (hopefully) time to do the other levels
of documentation, like tutorials and so on -- which are often best written
by someone other than the developer, simply because with the best
will in the world some things that are "obvious" to them that may not be
obvious to your customers.

HTH

Christopher Gooch, Technical Author,
LightWork Design Ltd., Sheffield, England. 
chris -at- lightwork -dot- co -dot- uk    www.lightwork.com








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

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems 
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East, 
June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline 
April 27. http://www.pdfconference.com. 

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