At a previous CouchDB IRC meeting I mentioned that Cloudant had worked up a new approach to documentation, capable of including per-language examples AND being hosted in CouchDB itself. I'd like to share the links, get feedback and see if the community is interested in helping develop it further.
Before anyone thinks I am taking credit here, I'm not - I'm just the messenger. This exists solely through the good work of Diana Thayer (@garbados), Brad Noble (@bradnoble), Kim Stebel (@kimstebel), Sean Barclay (@seanbarclay) and others whose names escape me at present. Thank you for getting us this far, everyone! First, the link: http://is.gd/cloudant_doc_rewrite This is an extract of the Cloudant API reference docs, converted to tripit's Slate framework, and maintained as a couchapp by garbados' quilter tool: https://github.com/cloudant-labs/slate https://github.com/garbados/quilter As you scroll through the reference, be sure to try the curl and node.js tab links. (The http and python ones are not as complete.) The idea here is to have the examples inline with the API reference, and to provide them in the language of choice for developers. Advantages: * Self-hosted documentation. Why aren't we doing this yet? * Built-in examples in many languages. Yum! * Markdown driven (if you <3 .md) Disadvantages: * Markdown, not ReStructuredText driven (if you <3 .rst) * 1-time conversion to .md required * More tooling to support Is this something the community would be interested in helping build/maintain/incorporating into CouchDB? -Joan
