General structure

[tpluscode]

Off the top of my head, I just thought that I'd reorganize the cookbook pages in three general categories or angles:

1. Hydra concepts
   • details of interpreting different structures represented by Hydra Api Doc and resource representations
2. Implementing the client
   • Slightly overlapping with the above but with emphasis of client behavior rather static analysis
3. Implementing the server
   • Server's perspective on Hydra requests and behavior

Now, this could be done twofold. Either we have those as top level categories and pages which slightly overlap, or structure individual articles so that the cover all three areas where possible. So that each cookbook article approaches the given subject at 3 angles.

[angelo-v]

Seems to be a reasonable struture. From gut feeling I would prefer the latter option having one article with 3 perspectives, but I guess we just should try out.

[alien-mcl]

I'm not sure. Concepts feels to be redundant with spec. I always look for real meat - examples of specific usages when I want to quickly implement something that works in technology I don't now to well.
That's why I've started from use cases as these carry one important (from my perspective) information:
what can be done with / what you can expect from hydra

Still - showing each use case with various perspectives (client/server) is a go go :)