Most intuitive, readable API / language reference documentation

Question

I'm working on the dreaded last stage of a project: documenting the API for a semi-technical audience.

I'm wondering: what API docs have you found to be particularly elegant?

Note that this has nothing to do with how elegant the API itself is: this is purely a question of the formatting/appearance of the API docs themselves. Which language or API docs convey their information in the most intuitive and readable way?

Answer 1

Two off the top of my head:

• Zend Framework
• Python ( uses Sphinx )

Answer 2

Python has very compact, but amazingly clear documentation:

http://docs.python.org/index.html

Answer 3

A negative answer from me - just to document what I've found horrible.

Maybe it is just a case of living mostly in Microsoft land but I've never seen an API documentation language that I can read as easily as code.

The two documentation sources I read regularly are the SQL Server Books Online and the MSDN C# documentation. I absolutely loathe the technical documentation langauges employed on both. I find that almost 100% of the time I dive straight to code examples.

For example, below is a few lines from the t-sql reference on select - I write select statements every day yet really struggle with this:

SELECT statement ::= 
    < query_expression > 
    [ ORDER BY { order_by_expression | column_position [ ASC | DESC ] } 
        [ ,...n ]    ] 
    [ COMPUTE 
        { { AVG | COUNT | MAX | MIN | SUM } ( expression ) } [ ,...n ] 
        [ BY expression [ ,...n ] ] 
    ] 
    [ FOR { BROWSE | XML { RAW | AUTO | EXPLICIT } 
            [ , XMLDATA ] 
            [ , ELEMENTS ]
            [ , BINARY base64 ]
        } 
]

It is only in the case of wanting to dig into a very detailed or edge case requirement that I ever take the time to relearn to details of the documentation language. But for myself at least, the actual documentation syntaxes evaporate once they've served their need.

---

EDIT - I felt the need to be a little bit positive about MSDN, I use it most every day and find it to be a great wealth of information, but it is generally the code samples and the explanatory text, not the API documentation that give me the information that I need.

Answer 4

Django.

Answer 5

Python's documentation is my favorite.

Answer 6

I'm going to have to go with the MSDN Library. They do a particularly good job of documenting pre/post conditions of methods and excellent consistency across a HUGE set of APIs.

Answer 7

Flex...I really find this sort of setup perfect.

Answer 8

I've always liked the javadocs and tutorials for the Java standard library.