API Documentation
I have been developing applications and frameworks for a long time. Most of them have exposed APIs for third-party developers. I have also, of course, consumed a great many APIs, libraries and frameworks from a variety of sources. We are always told that we must document our code, usually in the form of comments and maybe in the form of technical and design documentation. In the real world though, what form should this take? Developer Documentation I work mostly in the .NET world, so the most obvious starting point is to write XML comments in the code itself. This does two things: Places the documentation close the code itself. This, in theory, means that the documentation is more likely to be maintained as the code evolves. As the developer writes the code they should, hopefully, consider the interfaces they are writing from a consumers perspective. I reason that if I can't describe in words what the the method I am writing does how on earth can I expect someone els