Add "walkthrough" for GCS to our docs?

A lot of people are brand new to these cloud services, so I'm wondering if it's worthwhile to have a top level that basically shows you "here's what you do from start to finish" with gcloud-node.

Thinking something along these lines: https://github.com/GoogleCloudPlatform/gcloud-python/blob/master/gcloud/datastore/demo/demo.py

Any opinions?

I think this is cool, but maybe we could just give each service a page on our docs that would show something similar. And if we went crazy (which I always endorse), we could test them against a real backend programmatically.

I'd be down for that. The goal would be "If you're new to , go here to check out the ' in 10 seconds" page... or something like that.

Yeah, and being able to link right to the docs that list the parameters of the methods/show other examples/etc would be convenient for users as well.

The biggest hurdles for new people seem to be:

Creating a project
Enabling the APIs
Knowing the difference between 'project name' and 'project id'
Creating credentials (the right kind of credentials)

For storage, the biggest hurdles seem to be..

Knowing you need to create a bucket (that the one in the examples doesn't already exist for you...)
That bucket names are globally unique

For some of these, I think screen-shots are going to be important.

I suspect that if we could share these across the languages (since they aren't really specific to Node), it would save others a lot of time also.....

Hmm, what would be the best way to share? Have a heading in each client lib's readme that would link to a MD file in this repo (or any of our repos for that matter)? We could also create a new repo just for this (gcloud-client-library-introduction or something similar) that the link could point to.

All of our gh-pages docs can link out to this as well.

For language specific things (here's how you get started w GCS + gcloud-node), I'd expect those to live in the repo (ie, gcloud-node).

For common things (here's how you create a service account), maybe we can put those into gcloud-meta, and do an {{ include "gcloud-meta/docs/whatever.md" }} or something similar... ?

For language specific things (here's how you get started w GCS + gcloud-node), I'd expect those to live in the repo (ie, gcloud-node).

Yeah, we should still definitely have walkthroughs that show the logistics of using our libs.

For common things (here's how you create a service account), maybe we can put those into gcloud-meta, and do an {{ include "gcloud-meta/docs/whatever.md" }} or something similar... ?

I think since gcloud-meta is private, that would create issues. It would also be nice to keep the source file publicly visible where a contributor can send a PR if necessary.

The approach of including an md file that way in our docs is a good one, though.

Yes, the assumption would be that gcloud-meta wouldn't be private anymore... so that people can edit this...

SGTM.

Maybe we could have a gcloud-common repository -- which would have markdown files and images for shared docs?

That might be a little too meta, if we're already getting the mutual docs from gcloud-meta, though I think it's a better name than "gcloud-meta". Opened https://github.com/GoogleCloudPlatform/gcloud-meta/issues/11 to get the ball rollin'