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

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

Yvonne DeGraw wrote:
> 
> While you can get the actual actions performed by an API function from the
> code or a programmer, the API's "side effects" are not something that the
> programmer is going to think about putting in comments because they don't
> have a user focus when writing comments.
> 

Comments like this make me more aware of the differences in the open
source community, where I've been doing most of my work in the last few
years.

Many open source projects are collaborations via the internet, between
groups of people who have never met. One result of this work method is
frequently very heavily commented code. In a couple of cases, I've seen
virtually complete configuration instructions included in the coments,
so that the comments were several times longer than the code.

It doesn't always happen that way, not by a long shot, but it happens
enough that I'm a little spoiled: I expect detailed comments.

-- 
Bruce Byfield 604.421.7177 bbyfield -at- progeny -dot- com

"And if you had some spirit then it wouldn't be so bad,
It's your awesome anonymity which makes me get so mad."
- Attila the Stockbroker, "Vegetables"

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

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