Thanks for the response. See my response to bduerst in this same thread - it was that page.

Also to be clear - I don't think this particular example I gave is the end of the world/egregious - I just used it as representative of the fact that the general pattern I've seen of the docs following where details are explained, but the "obvious" bits of simple usage are not discussed.