Disclosure: I work for Google on the App Engine team doing documentation.

Firstly, a sincere thank you for reading and caring about our documentation.

With regards to the page you referenced, would you please elaborate on what information would help you come to the appropriate conclusion about using a second generation runtime? Your feedback would be very useful to us in order to shape this page into something that provides you with actionable information rather than "useless marketing junk" :)

Also to address a point you made in the first paragraph of your post, the PHP 7.2 beta runtime is a "second generation" runtime.

Cheers

Hi, I couldn't agree more with the parent comment about the AppEngine docs. I built a fairly small app and it was utterly excruciating to sort out the nuances.

There should be right up front, a crystal clear page detailing the three possible environments.

- Legacy Standard (WITH A VERY CLEAR DEPRECATION NOTICE)

- Legacy Flexible (WITH A VERY CLEAR DEPRECATION NOTICE)

- Standard Second Generation GVisor

For example, in Python Standard (old standard), it's extremely confusing to work out which gcloud libraries are bundled, and which need to be vendored and packaged into the app (yes I know there is a page that tries to explain. It's unclear).

Thank you for working on the documentation. It is the number one area that GCP needs to invest in. All the technology is miles ahead of AWS in the core areas. The docs however, are very very far behind.

Happy to elaborate more if there's any specifics you need.

> For example, in Python Standard (old standard), it's extremely confusing to work out which gcloud libraries are bundled, and which need to be vendored

I agree. I spent a lot of time trying to figure this out myself with various APIs, and in some instances, I gave up and looked for an alternative after I failed to figure out how to correctly vendor some Google Cloud libs (even following what documentation I did find, which made it look so simple).

Sure, and apologies for the harshness in my original post.

My main complaint about the marketing landing page at https://cloud.google.com/appengine/ is that it doesn't contain any immediate information about the different environments. It does have a link to "Choosing the right Environment" but it's _waaay_ down below the fold. In general I wish Google Cloud product pages had their big "View Documentation" buttons up at the top next to the free trial button, instead of way down below the pricing section.

In addition, neither the "Choosing the right Environment" nor the "App Engine Standard Environment" docs linked at the bottom of the product page contain detailed information about the second-generation standard environment, which is frustrating. I do appreciate that the language-specific pages in the main docs link contain a short comparison that includes the beta environments, at least.

That said, the primary document comparing the environments (https://cloud.google.com/appengine/docs/the-appengine-enviro...) seems very out of date. For example, it mentions you should use the flexible environment if your app:

> Depends on other software, including operating system packages such as imagemagick, ffmpeg, libgit2, or others through apt-get.

However, the Node standard environment contains these three packages and more (https://cloud.google.com/appengine/docs/standard/nodejs/refe...).

There might be other nit-picks to be said, but really, my main criticism of the documentation is that trying to understand the split between "standard/flexible/second-generation standard" environments at first glance is tricky. I'm sure y'all have plans for this going forward as these environments come out of beta, so I'll hold off on whining too much more. Thanks for asking for further feedback, and for clarifying that the new PHP runtime is a second generation one.

Thank you all for the feedback, it is extremely useful for us.

From this, I believe the action items for us (apologies if I have missed out anything, please correct me):

* Work on making it clearer which environment and which runtime you should choose for your apps and cut out the marketing prose.

* Provide more technical details on the differences between first generation and second generation runtimes.

* Be explicit on what libs are provided and what need to be vendored.

If y'all want to provide more feedback please feel free to add to this thread (I'll be checking it periodically for a few days) or contact me via email - lla@(you know the domain).

Disclosure: I work for Google on the App Engine team doing documentation.

[I'm a technical writer at Google working on Cloud documentation]

Thank you for the constructive comments regarding GCP and in particular documentation; we are working on addressing the points raised.

GCP has a dedicated tech writing team which is growing (we're hiring!) and the documentation is written by tech writers. We work with our colleagues in developer relations (developer advocates, developer programs engineers), UX and the software engineers who created the product.

All that said, we know our documentation is not perfect and are constantly working to improve. To that end if you see something that is broken/incorrect, please file a bug (the "SEND FEEDBACK" link in the top right of the documentation page is a bug submission form). We love to hear from users and I can assure you docs bugs do not get routed to /dev/null (we have a bug SLO, just like our SWE colleagues).

As a more general tech writing comment, documenting large, fast growing distributed systems such as public clouds is tricky. There's a lot more to documentation than just writing up instructions, such as thoughtful information architecture. It's a challenge that we, and I'm sure our counterparts at AWS et al., are grappling with.

As tech writers, we wince when we see errors in our work and feel pain when users are not able to enjoy the product/service as intended due to issues in documentation. The whole developer relations team (DAs, DPEs and tech writers) proactively try and catch these mistakes but of course, we miss some. It is nice to see users feel so passionately about documentation, so please let us know where we have made mistakes and we will fix them and try harder next time.