This website presents an interactive architecture diagram of the Linux kernel. The diagram breaks the kernel into a grid of functionality and layers with the ability to pan and zoom the map. You can then click on a specific item to look it up in the Linux source code.

One of the problems of providing documentation for a large project such as the Linux kernel is how to make the information manageable to navigate. This interactive diagram is a great way to provide an overview of all the available APIs and gives developers a jumping off point into the API documentation (although in this case it is an index to the actual code, rather than a documentation index).

• http://www.makelinux.net/kernel_map.shtml

Peter Gruenbaum wrote a great article on best practices for producing documentation for Web-based APIs. He notes the importance of auto-generating API documentation, including sample code, showing example requests and responses, and explaining authentication and error handling.

• http://blog.programmableweb.com/2010/08/12/web-api-documentation-best-practices

There are many tools out there that will create API documentation automatically from the comments in your code. Doxygen is one that I have used a lot and also like a lot. It can extract documentation from many different languages, including C and C++, it works on Windows, Mac OS X, and Linux, and it has a huge degree of configurability. It’s also open source. Check it out for your API reference documentation needs.

• http://www.doxygen.org/

Steven Clarke is a usability engineer at Microsoft and wrote an article for Dr. Dobb’s called “Measuring API Usability.” In this article he talks about applying usability to API development and how it can help to produce better interfaces. He also presents the cognitive dimensions framework, which offers 12 factors that impact the way a developer works with an API. Steven also talks about how to map these cognitive dimensions to different developer profiles, such as opportunistic, pragmatic, and systematic engineers.

• http://www.drdobbs.com/cpp/184405654

Martin Robillard of McGill University wrote an article for IEEE Software called “What Makes APIs Hard to Learn? Answers from Developers.” In this work, Robillard used survey results from 77 developers to find out the main obstacles they faced trying to learn a new API. The key indicators were issues with the design of the API and inadequate resources such as documentation. Read the article for more detail and nuance though.

• http://www.computer.org/cms/Computer.org/ComputingNow/homepage/2009/1109/rW_SW_APIsHardtoLearn.pdf