Best practices for writing API documentation

Yesterday I found a great blog post from Mark Tattersall via Twitter. It is about best practices and patterns for writing API documentation he identified when improving his own API at Braintree. Thank you Mark for your great work ;).

Why should I write comments?

Nearly everytime when talking about commenting interfaces or source code, the question "why documentation?" is raised. I realized that there are a lot of different motivations for writing some comments in natural language. My personal one is that I use writing in natural language as a tool to reflect my own thoughts. If I am not able to explain or formulate something, this might indicate that my solution is not ready right now.

So why should I write a contract for an operations? In this posting I try to collect some reasons for writing a contract. Here is my current list:

• Reflect my own work or thoughts
• Specify a task (for another person)
• Get juristic safety when providing software-operation to another, external organization (e.g. another company).
• Define what an operation should do (e.g. for later maintenance: its easier to decide if the implemented operation does things correctly)
• Agree with somebody else on an operation and work in parallel on it (more precise as only with code)
• To be continued ...

Feel free to post your reasons with a comment :). I am very excited to read them.