Help users draw the rest of the owl

[itowlson]

WAC has a handy readme which shows plugging a function export into a function import. For more complex compositions, it directs you to the language guide. Unfortunately, I'm afraid I found the language guide overwhelming, and struggled to see how to map it onto even simple use cases. (My use case at hand was "I want to plug two interfaces together, rather than two functions.")

There is some coverage in the component model book (https://component-model.bytecodealliance.org/composing-and-distributing/composing.html), so I am not sure if it would be better to build that out, or to reorganise the repo docs into a learning guide/cookbook vs advanced reference. But it would be great to have something to cover that intermediate ground and to help users get more comfortable with WAC.

I would suggest a learning guide/cookbook would:

• De-emphasise the "superset of WIT" and evaluation order stuff
• Focus on interfaces (not necessarily to the exclusion of functions, but as the default starting point)
• Focus on common patterns (plug, adapter, middleware chain, fan-out, ...?)
• Guide the reader's intuition by using meaningful names (e.g. "oauth:authenticate" or "regex:expression" or "print" rather than a, b and i)
• Explain when you would use constructs (e.g. when would I use import?)
• Explain the differences between constructs (import is "to import an instance", but new "instantiates a component and returns a component instance" - so which do I use?)
• Explain concepts (there are instances, are these like running instances?)
• Motivate expressions by usage (e.g. show a real usage of spread, when would I want "postfix access" vs "postfix named access")

I'm happy to help with this, although because of the aforementioned overwhelming and struggling I don't yet feel confident to figure most of it out myself! But I'd be happy to work with the WAC devs on something if you're open to it!

cc @kate-goldenring @vados-cosmonic for documentation SIG input and thoughts