{"action":"created","issue":{"url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-node/issues/1084","repository_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-node","labels_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-node/issues/1084/labels{/name}","comments_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-node/issues/1084/comments","events_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-node/issues/1084/events","html_url":"https://github.com/GoogleCloudPlatform/gcloud-node/issues/1084","id":128520475,"number":1084,"title":"Update overviews with more detailed code","user":{"login":"jgeewax","id":112928,"avatar_url":"https://avatars.githubusercontent.com/u/112928?v=3","gravatar_id":"","url":"https://api.github.com/users/jgeewax","html_url":"https://github.com/jgeewax","followers_url":"https://api.github.com/users/jgeewax/followers","following_url":"https://api.github.com/users/jgeewax/following{/other_user}","gists_url":"https://api.github.com/users/jgeewax/gists{/gist_id}","starred_url":"https://api.github.com/users/jgeewax/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jgeewax/subscriptions","organizations_url":"https://api.github.com/users/jgeewax/orgs","repos_url":"https://api.github.com/users/jgeewax/repos","events_url":"https://api.github.com/users/jgeewax/events{/privacy}","received_events_url":"https://api.github.com/users/jgeewax/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-node/labels/docs","name":"docs","color":"0052cc"},{"url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-node/labels/enhancement","name":"enhancement","color":"84b6eb"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":17,"created_at":"2016-01-25T11:51:48Z","updated_at":"2016-03-24T14:20:23Z","closed_at":null,"body":"Right now, clicking on a service (ie, Datastore) in the docs brings me to a page that has a brief overview and then the stuff that happens to be at the top level (like... `int` and `double`).\r\n\r\nCan we restructure this a smidge?\r\n\r\n1. Move `double` and `int` somewhere else (at least in the docs?)\r\n  On this page, I'm really not looking for such a low-level detail, I'm looking for high-level stuff. If I want to get an idea of how to store special types, I'd be looking for a like to \"Types\" or something along those lines.\r\n\r\n1. The brief overview is fine, but it's bascially a `301` in that it says \"you really want the `dataset` result... take a look at that\". Can we make this act as a more friendly and (somewhat) comprehensive overview? Basically \"here's the typical use case for [service], and how you write code to do it\".\r\n\r\nFor example, with Datastore:\r\n\r\n\"\"\"\r\nThe `gcloud.datastore` object gives you some convenience methods, as well as exposes a `dataset` function. This will allow you to create a `dataset`, which is the object from which you will interact with the Google Cloud Datastore.\r\n\r\nThe basic flow is:\r\n\r\n1. Establish a connection to Cloud Datastore:\r\n  ```js\r\n  var gcloud = require('gcloud')({\r\n    projectId: 'grape-spaceship-123',\r\n    keyFilename: '/path/to/keyfile.json'  // You can get this from the cloud console\r\n  });\r\n\r\n  var datastore = gcloud.datastore;\r\n  var dataset = datastore.dataset();\r\n  ```\r\n\r\n  (Now that you have a `dataset` reference, take a look at the [link to dataset docs])\r\n\r\n1. Add a `TodoItem` entity (if you don't know what an entity is, click here [link to entity concept on cloud.google.com]):\r\n  ```js\r\n  var key = dataset.Key('TodoItem');\r\n  var data = {title: \"Buy milk\", due: new Date('Tue May 12 2015 15:30:00 GMT-0400 (EDT)')};\r\n\r\n  dataset.save({key: key, data: data}, function(err) {\r\n    if (err) {\r\n      console.log(\"Uh oh, something went wrong:\", err);\r\n    } else {\r\n      console.log(\"Todo item saved:\", key.path); // ['TodoItem', 5669468231434240]\r\n  });\r\n  ```\r\n\r\n1. Retrieve your entity by it's key (if you don't know what a key is, click here [link to key concept on cloud.google.com]):\r\n  ```js\r\n  var key = dataset.key(['TodoItem', 5669468231434240]);\r\n\r\n  dataset.get(key, function(err, entity) {\r\n    if (err) {\r\n      console.log(\"Uh oh, something went wrong:\", err);\r\n    } else {\r\n      console.log(\"Your entity is:\", entity);\r\n    });\r\n  ```\r\n\r\nThe other things you might want to do are:\r\n\r\n- Run queries (\"Give me all TodoItems due tomorrow\"): [link to query docs]\r\n- Do multiple operations in one atomic group: [link to transactions docs]\r\n\r\n\"\"\"\r\n\r\n(And remember -- these code snippets must be **tested** so that if our code would break them, the tests fail. We can't have docs out there that don't work...)"},"comment":{"url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-node/issues/comments/200859629","html_url":"https://github.com/GoogleCloudPlatform/gcloud-node/issues/1084#issuecomment-200859629","issue_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-node/issues/1084","id":200859629,"user":{"login":"jgeewax","id":112928,"avatar_url":"https://avatars.githubusercontent.com/u/112928?v=3","gravatar_id":"","url":"https://api.github.com/users/jgeewax","html_url":"https://github.com/jgeewax","followers_url":"https://api.github.com/users/jgeewax/followers","following_url":"https://api.github.com/users/jgeewax/following{/other_user}","gists_url":"https://api.github.com/users/jgeewax/gists{/gist_id}","starred_url":"https://api.github.com/users/jgeewax/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jgeewax/subscriptions","organizations_url":"https://api.github.com/users/jgeewax/orgs","repos_url":"https://api.github.com/users/jgeewax/repos","events_url":"https://api.github.com/users/jgeewax/events{/privacy}","received_events_url":"https://api.github.com/users/jgeewax/received_events","type":"User","site_admin":false},"created_at":"2016-03-24T14:20:23Z","updated_at":"2016-03-24T14:20:23Z","body":"Just to clarify, the Ruby guys did a pretty nice job here:\r\n\r\n- Ruby (nice pretty overview): http://googlecloudplatform.github.io/gcloud-ruby/docs/v0.6.2/Gcloud/Bigquery.html\r\n- Node (not quite there yet): https://googlecloudplatform.github.io/gcloud-node/#/docs/v0.29.0/bigquery\r\n\r\nI wonder though if we can write a single \"article\" (markdown) with included snippets where only the language changes... and then we'd basically have a mapping of sorts...\r\n\r\n```js\r\ntasks = [{\r\n  \"service\": \"bigquery\",\r\n  \"language\": \"node\",\r\n  \"task\": \"datasets/list\",\r\n  \"snippet\": \"<some spec pointing to a snippet of code somehow>\"\r\n},\r\n...\r\n]\r\n```"}}