Add a banner saying that we're *not* the same as the googleapis module on the gcloud landing doc?

[jgeewax]

In #553, @byrneciaran mentioned that there was some confusion between gcloud and googleapis modules for talking to Datastore specifically. I think that might be a bigger issue of distinguishing for any of the cloud services.

Seeing as we can't change cloud.google.com yet to use gcloud for the examples, could we at least make a note somewhere in our docs saying that we're different, and you should stick with our docs for the most part?

Or is that overreaching?

[ryanseys]

Hmm, we already address this a bit in the README too by saying:

If you need support for other Google APIs, check out the [Google Node.js API Client library][googleapis].

Hard to say what we should do here with changing the documentation on cloud.google.com because the docs there aren't even up to date for googleapis since I overhauled the library last summer. 😨

[byrneciaran]

Just to add to this, in my case I'm new to Datastore (which btw is great!). I'm coming from SQL, Mongo, Postgres, DynamoDB and DocumentDB. The first stop for me was to Google "Datastore nodejs" and read up on the docs which all point to the googleapis. I only "stumbled" across the gcloud. I'm still not sure which came first, and why there is a gcloud? But, IMO it's much better and pretty nice to use. The big drawback is lack of documentation. For example, the Datastore docs don't mention anything about Datasets yet it's the first thing you come across once you get started with gcloud. I'm still confused about Keys as there's no documentation on what params to set for specifying ancestors, etc.

[jonface]

@byrneciaran I totally agree. The documentation is poor and currently I'm looking at the nodejs gcloud source to figure out what's going on. It's not ideal.

[stephenplusplus]

The docs can always be improved. We've been working hard to make a lot of improvements since this issue.

@byrneciaran sorry for the delay in getting answers for these questions.

I'm still not sure which came first, and why there is a gcloud?

We actually have both of these addressed on our FAQ: https://googlecloudplatform.github.io/gcloud-node/#/faq

the Datastore docs don't mention anything about Datasets yet it's the first thing you come across once you get started with gcloud.

I'm not sure if you're talking about this library, but if you were to click on Datastore, you'd get to: https://googlecloudplatform.github.io/gcloud-node/#/docs/v0.16.0/datastore. That page shows how to get a Datastore object and has a list of the methods, one being "dataset". Showing an example of how to use the dataset method might be helpful here.

From there or from the sidebar ("Dataset"), you can then get to https://googlecloudplatform.github.io/gcloud-node/#/docs/v0.16.0/datastore/dataset, which seems to cover the API pretty well. Is there something about our general site, hierarchy, or something else that simply makes things harder than they need to be?

I'm still confused about Keys as there's no documentation on what params to set for specifying ancestors, etc.

This library's docs just represent our library. We link out to the official service docs for users to learn more about the basics of the services and how they work, best practices, etc. We don't want to duplicate all of the documentation (which is a lot!) that already exists there.

@jonface can you be more specific about what is poor and needs fixing?

@jgeewax RE: https://cloud.google.com/datastore/docs/concepts/entities#Datastore_Properties_and_value_types where they show examples like:

var entity = {
  key: { path: [{ kind: 'Employee', name: 'asalieri' }] }
  // ... some properties ...
};
datastore.commit({
  // Request insertion with complete key specified
  mutation: { insert: [entity] },
  mode: 'NON_TRANSACTIONAL'
}).execute(callback);

I can see how this would be super confusing to a reader of those docs who we sent there from our docs for more information. Do we expect the cloud docs to ever show gcloud-node code? Assuming not or at least not for a while, is there a way to have the docs explain what library they're talking about for the example code? See below for a crude attempt at clarity:

[stephenplusplus]

I don't think our library can do much more to clear this up, as explained in my last post. It would be great to see the official docs specify what library they're using when they show code examples. That's probably the single-most thing that can help.

As stated above, if anyone else has suggestions for improvements, feel free to shout them out. For now, I think we've done all we can on our side.