{"action":"created","issue":{"url":"https://api.github.com/repos/cockroachdb/docs/issues/2849","repository_url":"https://api.github.com/repos/cockroachdb/docs","labels_url":"https://api.github.com/repos/cockroachdb/docs/issues/2849/labels{/name}","comments_url":"https://api.github.com/repos/cockroachdb/docs/issues/2849/comments","events_url":"https://api.github.com/repos/cockroachdb/docs/issues/2849/events","html_url":"https://github.com/cockroachdb/docs/issues/2849","id":310616029,"number":2849,"title":"Use an actual database for all docs examples","user":{"login":"rmloveland","id":1312291,"avatar_url":"https://avatars3.githubusercontent.com/u/1312291?v=4","gravatar_id":"","url":"https://api.github.com/users/rmloveland","html_url":"https://github.com/rmloveland","followers_url":"https://api.github.com/users/rmloveland/followers","following_url":"https://api.github.com/users/rmloveland/following{/other_user}","gists_url":"https://api.github.com/users/rmloveland/gists{/gist_id}","starred_url":"https://api.github.com/users/rmloveland/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rmloveland/subscriptions","organizations_url":"https://api.github.com/users/rmloveland/orgs","repos_url":"https://api.github.com/users/rmloveland/repos","events_url":"https://api.github.com/users/rmloveland/events{/privacy}","received_events_url":"https://api.github.com/users/rmloveland/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":1,"created_at":"2018-04-02T21:22:25Z","updated_at":"2018-04-10T15:47:36Z","closed_at":null,"author_association":"CONTRIBUTOR","body":"It would be extremely helpful if the entire documentation set could use one actual database that you could run queries against.\n\nSome benefits of this approach would include:\n\n- Better reproducibiliy and manual testability when writing docs, e.g., right now I am working on #2555 and I am re-populating a table \"by hand\" (possibly on 3 different binary versions) to test a single code snippet wrapped in a transaction\n\n- Better automated testing (see #182)\n\n- Better practices can be enforced if everything is in one jointly-maintained DB (see #190)\n\n- Automation of various kinds can be explored that are not possible right now (related in spirit to #2819)\n\n- Users could run the examples very easily while learning the DB.  For example, if this hypothetical DB were a `cockroach gen` output, they could have their own copy of the exact DB used to document everything running locally, eliminating any time lost to \"guess and check\" with the example code on the site.  The user can just copy-pasta it right into the prompt and see the exact same results.\n\n- Examples would be \"cut from the same cloth\", in much the same way that C.J. Date's books use the parts database.  This helps reader comprehension since the context for the example is more easily understood.  Once you learn the parts database you can just focus on understanding the section about `JOIN`s or whatever, you aren't thinking too much about other aspects of the tables.\n\nA drawback is that it might not be that easy to design an example database that covers all of our documented features.  And it could prove hard-ish to maintain for various other reasons, such as needing to update `cockroach gen` (if we went that way, but it seems like that would be the best way in principle to accomplish this).\n\nHowever, I think the benefits would outweigh the drawbacks.  I think it would be a big win for users.\n"},"comment":{"url":"https://api.github.com/repos/cockroachdb/docs/issues/comments/380149836","html_url":"https://github.com/cockroachdb/docs/issues/2849#issuecomment-380149836","issue_url":"https://api.github.com/repos/cockroachdb/docs/issues/2849","id":380149836,"user":{"login":"jseldess","id":15893490,"avatar_url":"https://avatars2.githubusercontent.com/u/15893490?v=4","gravatar_id":"","url":"https://api.github.com/users/jseldess","html_url":"https://github.com/jseldess","followers_url":"https://api.github.com/users/jseldess/followers","following_url":"https://api.github.com/users/jseldess/following{/other_user}","gists_url":"https://api.github.com/users/jseldess/gists{/gist_id}","starred_url":"https://api.github.com/users/jseldess/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jseldess/subscriptions","organizations_url":"https://api.github.com/users/jseldess/orgs","repos_url":"https://api.github.com/users/jseldess/repos","events_url":"https://api.github.com/users/jseldess/events{/privacy}","received_events_url":"https://api.github.com/users/jseldess/received_events","type":"User","site_admin":false},"created_at":"2018-04-10T15:47:36Z","updated_at":"2018-04-10T15:47:36Z","author_association":"CONTRIBUTOR","body":"@rmloveland, I think this is a larger project that we're going to have the time for in 2.1, so I'm marking this as \"later.\"  But it's definitely something we should investigate more, perhaps in conjunction with Product."}}
{"actor":{"display_login":"jseldess"}}