We need to expose the per-language docs for JS, Python, and Ruby somewhere online about rethinkdb HOT 4 CLOSED

I thought about this a lot and talked to @mglukhovsky, and I'm actually really split on this. There are a number of good reasons not to post these docs:

1. Maintaining these and the api page and making them both excellent is double the work. I don't feel comfortable posting half-baked autogen docs.
2. It will be unclear to people which docs they should use, especially if they're not consistent.
3. It will be tempting not to make the api page as good as it possibly can be (and it can be much better than now) if the generated docs are out.
4. It would complicate site deployment process.

I would prefer to hold off on this until we push out the next two revisions of the api page. If people still want autogenerated docs, let's revisit this then.

from rethinkdb.

So, I think this is slightly more complicated than that. In particular:

• At least for Ruby, the autogen docs are installed when the user installs the gem. I think this is true for Python too. If the user has a tool that gives them autocompletion with documentation (or really any tool, like Ruby's ri), it will use the autogen docs, which means they have to be good.
• Right now the autogen docs for Ruby are the most reliable documentation for it. When something's wrong or unclear in our main docs, I look at the Ruby docs to see how it should be. Since the autogen docs almost always get updated when the actual code is updated (since they're right there), this will probably continue to be true.
• Our main docs are organized by some universal structure, but the autogen docs are organized by the actual structure of the language. If the user is in Ruby, calls .class on something, and wonders "What can I do with a Single_Row_Selection?", the Ruby docs can answer that.

Also, these are probably already hosted by whatever is hosting the package (e.g. http://rubydoc.info/gems/rethinkdb/1.2.6.0/frames).

from rethinkdb.

I agree with @mlucy that because autogen docs are used for autocompletion and can in fact be viewed on RubyDoc (although I don't think the equivalent is true for packages on PyPi or npm), they should be polished. However, I would prefer to have one central place for people to find answers about the API, regardless of what language they're using.

There is a tradeoff between docs usability for a novice user (for which rethinkdb.com/api is clearly better, given that it presents info in a task-oriented manner), and users already working with the language and its autocompletion / language-specific tools.

However, I would very strongly prefer to keep the generated docs off rethinkdb.com, as @coffeemug correctly points out that it will immensely complicate both the jekyll build process for the site and splinter focus on which docs are primary sources for users. I would urge us to instead improve the usability of the main docs to compensate for their current shortcomings (e.g. main docs being wrong / unclear are not a reason to replace them with autogen docs, they're a reason to improve the main docs).

Note that there are many other projects that use this approach (one set of main docs across languages) and do not provide the autogen docs, and I've never had a strong need to examine the autogen versions.

from rethinkdb.

I still think the autogen docs are, by their nature, more detailed and much more useful in some situations, but I trust your judgement if you think leaving them off right now is a major usability win.

(Also, as an aside, I don't think the deployment process would have to be that painful. We already have make targets for publishing the drivers; we could make publishing also regenerate the docs and then push them to dotcloud or whatever.)

from rethinkdb.