Simplify: CRUDL AIPs by Teasing Out Child Collections into Separate AIP or Separate Subsections of their own Page

[matttproud]

Reviewing the various AIPs for CRUDL (resp. AIP 133, 131, 134, 135, and 132), they orient themselves around a collection of resources that live under a parent under a structure similar similar to /v1/publishers/1/books.

I think these AIPs would be better suited if their primary documentation was instead oriented around a top-level resource (e.g., /v1/books). Then, for handling resources under a collection, that could be discussed either as a separate AIP or as a dedicated subsection in each of the aforementioned AIPs.

The reason I suggest this is that putting the nested structure in the forefront of the documentation makes the overall context less accessible to new readers. Specifically, consider the example that option (google.api.http) each verb gets on the respective AIP document. It includes stringly-typed data like get: "/v1/{parent=publishers/*}/books". That's a bit of a mouthful for a newcomer to process. Something like "/v1/books" is a plain string literal that a reader does not have to interpret and connect to the sub-collection mention at the top of the AIP page.