James Yu has written a blog post titled "Designing Great API Docs" on a company blog and it was interesting to see what kind of advice it had. The post suggests that multiple guides should come with the API documentation because when it stands on its own, it is much harder for someone to learn how to properly use it. If all you see are methods and classes, it can be difficult to figure out the flow of the code.

According to Yu, your documentation should have at least these components:

• Reference: This is the listing of all the functionality in excruciating detail. This includes all datatype and function specs. Your advanced developers will leave this open in a tab all day long.
• Guides: This is somewhere between the reference and tutorials. It should be like your reference with prose that explains how to use your API.
• Tutorials: These teach your users specific things that they can do with your API, and are usually tightly focused on just a few pieces of functionality. Bonus points if you include working sample code.

Some of the other advice is given in the headings of the blog post:

• Remove abstraction with examples
• Minimize clicking
• Include a gentle quickstart
• Use multiple [programming] languages
• You can never over-communicate edge cases
• Sample applications

The interesting part is that this kind of stuff is re-discovered from time to time by software developers. Developers of libre/free software should already be familiar with much of the above advice since it can be found in the GNU Coding Standards: Documentation section. It includes this bit of helpful advice,

Some programming systems, such as Emacs, provide a documentation string for each function, command or variable. You may be tempted to write a reference manual by compiling the documentation strings and writing a little additional text to go around them—but you must not do it. That approach is a fundamental mistake. The text of well-written documentation strings will be entirely wrong for a manual.
...
The only good way to use documentation strings in writing a good manual is to use them as a source of information for writing good text.

I think the GNU approach is a combination of the components that Yu mentions.

[The manual for a GNU program should be] ...clear to a reader who knows nothing about the topic and reads it straight through. This means covering basic topics at the beginning, and advanced topics only later. This also means defining every specialized term when it is first used.

Yu's advice to minimize clicking means to reduce a manual to a single web page. Writing a GNU manual means you're using Texinfo which can be compiled into a single HTML web page and on the GNU website, most of the manuals come in multiple formats: single webpage, one web page per node/section, ASCII text, PostScript, and PDF.

I like the Guile manual because it includes references, guides, tutorials, and an API reference. Here's a sampling of sections that correspond to the types of components that Yu mentions:

• Tutorials
  • 2 Hello Guile!
  • 3 Hello Scheme!
  • 5.7.1 How one might extend Dia using Guile
  • 7.4.2 How to write an option specification
  • 7.3.9 Web examples
• Guides
  • 4 Programming in Scheme
  • 5 Programming in C
• References
  • 6 API reference
  • 7 Guile modules

There's a lot of information in the manual and it progresses somewhat in a beginner to advanced way. Documentation about hacking the Guile virtual machine is the final section and is the most advanced. The "Hello Guile!" and "Hello Scheme!" sections are near the beginning of the manual.

The GNU Coding Standards are worth a read and the advice about documentation should serve as a useful guide to writing manuals for your programs.