Remove references to auto-generated in Monitoring README

[bjwatson]

What

Change these lines in the NodeJS Monitoring README. Do not explicitly state that it is an auto-generated library. Also, do not say that "a handwritten layer is not yet available".

Why

GAPIC-only libraries will become the norm as the code generators become capable of producing client libraries faster than we can hand-write them. We do not want to lead with calling them "auto-generated", since that can have negative connotations and is not the defining feature of the library design.

Stating that "a handwritten layer is not yet available" suggests that one might eventually be available. We don't want to lead developers to believe that they might eventually have a different surface to work with (apart from major version updates).

Notes

@callmehiphop I think @landrito originally did this, but I could not assign this ticket to him. Could you or @stephenplusplus give him, @jmuk, and @swcloud the necessary permission to own issues here? Thanks!

FYI @omaray

[stephenplusplus]

I wrote those lines, and I think the distinction is very important currently, as there are no docs for the generated API or precedent for an API that doesn't have our conventions; most popularly, the hierarchy between resource types in any given API, i.e. Storage > Bucket > File (storage({ auth }).bucket('bucket-name').file('file-name')) and the ways you can stat/interact with them (object.get(), object.getMetadata(), object.exists(), object.delete(), etc).

Do not explicitly state that it is an auto-generated library.

Why not?

I think a document or addition to the README would be very welcome to explain how we intend to mix autogenerated and handwritten APIs. And if we're not ready for that yet, which I assume we aren't, I think the Monitoring document in its current form is an appropriate way to communicate the state of things now.

Stating that "a handwritten layer is not yet available" suggests that one might eventually be available. We don't want to lead developers to believe that they might eventually have a different surface to work with (apart from major version updates).

I agree on that. I assumed at the time we were going to offer handwritten layers for all generated APIs. Changing this to simply "a handwritten layer is not available for this API." is sufficient.

[bjwatson]

Mainly because "auto-generated" is not a selling point and isn't the defining feature of the layer. We are currently kicking around better terms to use for the various layers. I'm okay with acknowledging that Monitoring does not have a layer that the other client libraries have, as long as it doesn't sound like it's a sub-optimal experience as a result. I'm interested in @omaray's opinion on this issue.

BTW, if there are idioms that you're using across all/most APIs, we should discuss what they are and whether we can move them into GAPIC/GAX.

[stephenplusplus]

Gotcha, that makes sense. Any names you're considering that you want to share here? Maybe some more eyes on it would help spark some winners. What are the defining features of the generated APIs, from a non-contributor's perspective?

On the idiom note, I'll kick off an issue on the gax repo.

[bjwatson]

I don't think there's anything secret about it, and I agree that more eyes & brains would generate better results. Let me check with my teammates before exposing their brainstorming to the whole world. :)

Thanks, Stephen.

[stephenplusplus]

Issue sent over in googleapis/gax-nodejs#71

[bjwatson]

Thanks, Stephen.

[landrito]

The README has been updated to use a template made by @omaray. I made a PR to our staging repo to show the change. @bjwatson does the contents of this readme work for you?

[bjwatson]

@landrito I'm referring to the hand-written README for the google-cloud-node repo.

[bjwatson]

@stephenplusplus #2526 didn't fix this issue.

Whether or not we want to fix this is up to @omaray and @lukesneeringer. It's a product messaging decision.

[stephenplusplus]

cc @eoogbe who marked that PR as a fix for this issue (which is why it was auto-closed when the PR merged)

[evaogbe]

As far as I can tell, the README no longer has the offending lines, so this should be closed.

[bjwatson]

https://github.com/GoogleCloudPlatform/google-cloud-node/pull/2526/files#diff-04c6e90faac2675aa89e2176d2eec7d8R625

[evaogbe]

Oh that README. I didn't even notice it was there. Sorry about that.

[stephenplusplus]

The new location has no mentions of auto-generated: https://github.com/googleapis/nodejs-monitoring