I found this entertaining article for developers discussing the challenges of documenting code. Reading it really takes me back to a variety of situations I've been in! How many times have I worked with developers, only to be told how "self-documenting" their code is... only, of course, to find out that they just mean comments. And of course, they didn't comment everything. "Oh that's not important, anyone can figure that out by looking at it." Or my favorite response when I stumble up on something particularly interesting, "Gee I don't know why I wrote that."

Commenting code and documenting code, while related, are two different things. Comments make documenting easy, but comments can never substitute for good documentation :) Providing good documentation in your code makes the results of automated tools that generate API documentation skeletons more useful. While those tools make API documentation easier, you can't solely rely on them as your only source. Granted it's better than nothing, but if you really want people to learn and develop with your API, there is no better time investment than comprehensive API documentation, including code samples and tutorials.

Here is a list of resources I have found to be particularly helpful:

• This blog offers a great list of resources and advice for developing API documentation.
• The API Writer entry in Wikipedia is also very insightful.
• This study makes a wonderful checklist when evaluating API documentation.

In the open source community, good developer documentation increases the chances of a project being picked up and maintained by the community. Meaning, the developer can focus on making those shiny new features and hand off supporting the old rusty stuff!