Hacker News Reader

Comment by otterley | Hacker News Reader

Can we see a design document/theory of operations, please? It’s difficult to evaluate this effort without understanding exactly what it is - namely, the constituent components, their respective functions, how they work and relate to one another, etc.

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.

View on HN

Is this something like what you're looking for?

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!

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

Have you taken a look at the docs repo? 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.

Yes, but they don't fit the description I discussed above. Or at least they're not organized in such a fashion.

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 :)

Your doc is marked invite only, BTW.

So you found the Zipkin UI link in the Microsoft GitHub docs already?

Reply on news.ycombinator.com