3 ms·

Is this something like what you're looking for? https://github.com/knative/serving/blob/master/docs/spec/overview.md https://github.com/knative/serving/blob/ma

by dewitt 8y ago

Is this something like what you're looking for? https://github.com/knative/serving/blob/master/docs/spec/overview.md https://github.com/knative/serving/blob/master/docs/spec/ove... Or a little higher-level: https://docs.google.com/presentation/d/1CbwVC7W2JaSxRyltU8CS1bIsrIXu1RrZqvnlMlDaaJE/edit# 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 https://github.com/knative/serving/tree/master/docs Same for the other repos, like build and eventing. Thanks for asking!

otterley 8y ago
Not really, I'm afraid. Resource descriptions don't constitute a theory of operations, and the higher-level document you linked to is not public. 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. [1] https://www.consul.io https://www.consul.io
- labadav 8y ago
  Have you taken a look at the docs repo? https://github.com/knative/docs/blob/master/README.md https://github.com/knative/docs/blob/master/README.md We have the high-level overview and deeper dive into the details for each of the components, install instructions and samples.
  - otterley 8y ago
    Yes, but they don't fit the description I discussed above. Or at least they're not organized in such a fashion.
- jsolson 8y ago
  I once had an interesting argument about Learning Perl. 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 :)
xrd 8y ago
Your doc is marked invite only, BTW.

by dewitt 8y ago

otterley 8y ago

Not really, I'm afraid. Resource descriptions don't constitute a theory of operations, and the higher-level document you linked to is not public. 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. [1] https://www.consul.io https://www.consul.io

labadav 8y ago
Have you taken a look at the docs repo? https://github.com/knative/docs/blob/master/README.md https://github.com/knative/docs/blob/master/README.md We have the high-level overview and deeper dive into the details for each of the components, install instructions and samples.
- otterley 8y ago
  Yes, but they don't fit the description I discussed above. Or at least they're not organized in such a fashion.
jsolson 8y ago
I once had an interesting argument about Learning Perl. 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 :)

xrd 8y ago

Your doc is marked invite only, BTW.