StandardsForApiDocumentation

From MashupCamp

Standards for API Documentation

One of the obstacles to expand the mashup ecosystem is getting developers the information they need to create applications. This includes API reference, tutorials, examples, etc. But with such variety of APIs and the relative new-ness of this particular space, this is an issue.

David Berlind hosted this session on standards for API documentation. The group of about 30 included a number of API providers, developers and others.

Ideas, comments, discussion:

• General agreement: that samples, cut-and-paste-this-code is one of the most valuable tools for developers.

• How to best leverage the power of community to improve, contribute to, or other participate in the process?

• Ratings: can there be a way for developers to rate the quality of APIs, their reliability, etc.? Ex: CPAN currently has a star system for ratings.

• Alan Lewis from eBay noted they have 1000 pages of docs and 6 fulltime writers. But they still can't keep-up with everything the want to do documentation-wise. They are strating to use XML Schema with add'l metadata, with tools to automatically extract base docs. API Reference Docs, is a tool they open-sourced (xml.com story from Alan).

• How to matching the style/model of the documentation that matches the style/model of the mashup developer?

• Tutorials, Quick Starts, and Primers as important form of documentation

• Pointers to real-world applications built on top of the API.

• APIs can mean so many things right now. Ex: REST can be interpreted and implemented in many forms.

• Documentation can be important as a pre-sales tool if the documentation is weak then it can reflect badly upon the provider and discourage uptake. Clarity is important as are examples.

• Standard terminology/nomenclature and visual cues.

• Enabling Tools: Builders that can help you create an application step-by-step can be a form of documentation (or at least part of the developer education suite).

• API Search: it's important to make the docs searchable

• Screencasts as a documentation technique

• Bugs and known issues: can there be a standard for this information?

• Formal documentation: WSDL is the classic formal web services 'documentation'. Serving as the bottom-line technical contract. No such formal model for most REST-type APIs.

• Related topic: what about 'cloning APIs', re-using, or standarizing APIs? Naturally this would simply things. But, there are many pragmatic and commercial issues in the way. API providers have an incentive to raise the barrier to switching.

Misc Best practices (existing or proposed):

• A couple of good best practices cited from an internal Avaya project: developers used JavaDocs, then auto-extracted. Documentation started at the beginning of the development process where writers were there from requirements on through the rest of the project. End-to-end documentation (aka 'embedded writers' with the dev team).

• Keeping developers up-to-date (provider best practice): Use of email alerts and RSS feeds to keep informed of updates to docs and APIs. Idea: not just a documentation standard but also a 'communication standard'.

• Documentation as an interative process, not a one-time event. Especially should not be an end-of-project rush. Although in practice, as folks have seen, budget or time often forces this. How to mitigate?

• Scenario documentation as a possible model: A goal-oriented approach. Working from a set of use and scenarios to help developers get jump-started or to more corherently can walk through a variety of examples.

Potential issues:

• A disconnect between creators of standards, such as with W3C, and what developer actually need and use on a day-to-day basis.

• If this effort is volunteer effort (leaving from this session) it can be hard or unlikely to actually make happen (Marc Canter).

• How to scaling documentation? There's a large difference between the documentation needs of eBay's API and that of a small, experimental API with one method.

Best quote:

• On standard terminology: "We have standard terminology, we just don't agree on it".

Action items:

• We'll create a mailing list of the appropriate interest parties, particularly the API providers, to continue this discussion. Sign-up list was used at end of session.