Re: YOWZA--struck a nerve: Was Help API Documentation?

[Bruce Byfield <bbyfield -at- progeny -dot- com>]

Berk/Devlin wrote:
 
> In my experience, both as a programmer and as an API documenter, THERE IS
> VERY LITTLE INFORMATION IN THE CODE.  Lots of useful data points, but
> little information.  Stuff for a reference manual is definitely in there --
> you can get the list of classes, with their associated methods and
> attributes.  But descriptions of what those methods and attributes do, what
> the parameters actually mean, why the class hierarchy is the way it is.  No
> way.

It sounds to me that your experience has been unfortunate.

I've worked with some coders who don't comment their code properly. And
their excuse, just as you suggest, is that they don't have time to do
so.

However, I've worked with just as many who have come to realize that
detailed commenting is part of their job description, and needs to be
done. And that makes sense in an environment where people move from job
to job, or where many different people might be working on the code. Ina
couple of extreme cases, I've even seen companies unable to finish a
patch or revision because the code was commented and the only person who
understood it was on holidays.

And, BTW, even if the code isn't commented, you can do a lot with it so
long as you have a testbed that you use to destruction. Even several
years ago, when my knowledge of code was even spottier than it is now (I
can change "Hello, World" to "Hello, Sailor" and that's about it :-) ),
I found that the best way to document parameters in the several hundred
applets with which I had to deal was to learn what lines of code defined
parameters, do a search for those lines in each applet, then play with
the parameter on a testbed until something happened. I reinstalled
several times, but the method was quicker than tracking down programmers
who kept irregular hours.

-- 
Bruce Byfield 604.421.7177 bbyfield -at- progeny -dot- 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.