Peter Gruenbaum has written a great article in the November 2010 issue of MSDN Magazine about the why and how of documenting APIs . You can read it online here: Hello World! A Coder's Guide to Writing API Documentation.