I think this sounds like a good initiative Joan. +1 On 27 October 2014 22:52, Joan Touzet <[email protected]> wrote: > 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
-- Noah Slater https://twitter.com/nslater
