I’ve tried; tried to keep documentation updated in a Word doc or in HTML content site.  It just takes too much time and doco is the last thing I update when in a time pinch (all the time).

So here is what I did on my last project.  Focused on keeping the API documentation in the code.  It was still too much typing.

I found a tool that will generate the headers for the XML comments.  Download and install Ghost Doc.  Select the class, enum, or method – press CTRL-SHIFT-D … the comments are generated.  It does a good job reading the code and adding in a good description along with parameters.

GhostDoc: http://submain.com/products/ghostdoc.aspx

Now that your code has commnets – how do you pull it all together into a nice website.  Website because docs will die on the vine and no one will have access. 

Get CodeDoc.  CodeDoc is a free, shared-source tool from Dwell.Net that helps you generate a documentation set for your C# class libraries. CodeDoc converts XML comments into documentation topics, and lets you add "overview" topics. The output from CodeDoc is browser-based documentation browser with a table of contents and index. The documentation browser works either online (on a Web site) or offline (on a hard disk).

CodeDoc: http://www.dwell.net/

There is an associated Console app that runs to generate a doc folder with all the pages.  You will need to update the CodeDoc.xml so the tool knows where to pull and push everything.  Overview.htm, Sourcefiles.htm, SourceOverview.htm required updating for display messages when on the first few pages.

Run the Console app:

codedoc C:\@Code\iESP.WebServices\iESP.Webservices.Web\CodeDoc.xml

Documentation is generated.  Minimum steps to keep your API documented.  Really helps when working with partners or 3rd parties that use your web services.  Saved me some time.