bus_error

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.

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

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