I think adding diagrams is a great idea.  I think this now exists as a separate issue, but if it doesn't, I'll create it