Agreed.  It is definitely something for which we need to provide more/better docs and examples!