Thanks to everyone who played a part of this! The Google team is also watching this thread. Happy to answer any questions people have.
Just a comment here about this in general - given all the resources at Google’s disposal, I’m perplexed as to why we don’t see world-class (or even at least halfway decent) documentation being shipped along with the product at first release. As a community I think we need to demand higher standards in this area. If GNU can do it, Google certainly can.
https://github.com/knative/serving/blob/master/docs/spec/ove...
Or a little higher-level:
https://docs.google.com/presentation/d/1CbwVC7W2JaSxRyltU8CS...
There are a lot of technical docs in the individual repositories. You can get started, for example, with the serving docs under:
https://github.com/knative/serving/tree/master/docs
Same for the other repos, like build and eventing.
Thanks for asking!
By "theory of operations," I mean a design document, often but not always created before a line of code is written, that describes in plain English what is to be built (or, what was built). It often discusses things like:
* What problems are being solved?
* What attempts have already been made to solve the problem?
* How does it work? How do the components interrelate? How does one operate it, especially at scale?
* How does this solution solve the problems better than the alternatives?
There are lots of great examples out there. I like to point to Consul[1] as a textbook example of fantastic documentation, and it's been there since day 1. Google would do well to follow Hashicorp's and GNU's lead.
We have the high-level overview and deeper dive into the details for each of the components, install instructions and samples.
The first chapter, when I picked up the book, was a tour of Perl. I loved it. It showed me all of the highlights with no details at all. I never read another chapter, and instead picked up the second book in the series to use as a reference.
My counter in this argument HATED that first chapter. They almost didn't read another one, because it put all of these examples in front of them with no depth. They thought the book would be much improved by removing that chapter.
I would have been bored to tears by the book this person wanted to read.
I'm not going anywhere in particular with this, except to say that the world takes all kinds. Sometimes docs don't exist simply because nobody realized someone else would find that shape of document useful, so they decided not to write it.
The docs I love may well be the docs you hate :)
Obviously this is a conflict of interest for Google, but just curious if you know of any plans in the works for being able to run this on AWS EKS? It's the obvious omission from the list of supported clouds on the installation page[0].