Re: Help API Documentation?

Subject: Re: Help API Documentation?
From: Chris Gooch <Chris -at- lightwork -dot- co -dot- uk>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 24 Apr 2001 13:33:12 +0100

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

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*

+ I keep a list of all "changed" man pages in the run up to each
I then basically perform a QA type job on them, and either edit/fix
pages as appropriate, or even sling back for more work from the
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
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
there aren't any irate customers reading ;-) ).

As I say, the important point is to get the responsibilities you expect of
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.


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


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

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 for more resources and info.

Previous by Author: RE: pronouns and portfolios--bringing it back tech writing
Next by Author: Re: Intro to API (Was: YOWZA--struck a nerve: Was Help API Docume ntation?)
Previous by Thread: YOWZA--struck a nerve: Was Help API Documentation?
Next by Thread: Re: New TECHWR-L Poll Question (Certification)

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

Sponsored Ads