Comment by Paracompact

Including the technical spec explicitly is still a good idea. Examples without a word of summary would just be strange!

It's merely that I think unstructured English is not a good language for communicating knowledge of how to use an API.