Add "walkthrough" for GCS to our docs?

[jgeewax]

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?

[stephenplusplus]

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.

[jgeewax]

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.

[stephenplusplus]

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.

[jgeewax]

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.....

[stephenplusplus]

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.

[jgeewax]

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... ?

[stephenplusplus]

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.

[jgeewax]

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

[stephenplusplus]

SGTM.

[jgeewax]

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

[stephenplusplus]

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'

[jgeewax]

Yea the idea would be... gcloud-meta stays private, gcloud-common is shared docs. Thoughts?

[stephenplusplus]

I kinda liked going all out open with one repo, but your call.

[stephenplusplus]

I think this issue will be solved by #1084 which is talking through concrete ways to implement. Feel free to re-open if I missed anything.