Comments (4)
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:
- 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.
- It will be unclear to people which docs they should use, especially if they're not consistent.
- 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.
- 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.
Related Issues (20)
- download.rethinkdb.com is down, 502 Bad Gateway HOT 2
- Evaluate Profile-Guided Optimization (PGO) on RethinkDB
- error: to_string called on an uninitialized ip_address_t, addr_type: 0 compiling rethinkdb on Raspberry HOT 6
- RethinkDB not fully supported on Raspberry PI OS Bullseye (32/64 bit) HOT 10
- Reasonable to change hard-coded cluster size? HOT 5
- help bro my issue = warn: Problem when checking for new versions of RethinkDB: HTTP request to update.rethinkdb.com failed. HOT 1
- cluster connect/reconnect timeout HOT 1
- Installation fails in Kubuntu 23.10 HOT 4
- Generate web_assets.cc in a repeatable file order HOT 1
- Avoid full paths of coffeescript files in generation of web_assets.cc HOT 2
- Rethinkdb 2.4.4 release list HOT 11
- Support protobuf 25
- Return multiple changes feed
- Cache miss rate measurements HOT 4
- Something i forgot to had when having the default doc like so
- Connect rethinkdb directly from browser ? HOT 1
- Why exactly do rethinkDB add null characters to response / request JSON ? HOT 5
- I could not install RethinkDB in Ubuntu 24.04 HOT 3
- How to handle NaN error in javascript Driver? HOT 3
- Is it just me or is there a problem with the download page? HOT 11
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from rethinkdb.