This is a proposal for how to draw diagrams of content models so that there's a common understanding of what they mean. Developers are likely to be passignly familiar with UML but not everybody is. This proposal takes a few elements from UML and explains how they map from objects to items.

Most of the time, we'll see rough diagrams on the whiteboard based on these elements. To make something more clean-looking, tools like OmniGraffle on the Mac can be used pretty easily (like the first two attachments/images below). I'll attach an OmniGraffle "palette" that I threw together based on this proposal.

There's lots of room for creatively extending this -- just start writing inside the square to tell more about the item or kind, for example. Usage will probably evolve too although we should try to keep it simple.

Basic elements

• Kinds and items are shown in squares
• Attributes are shown in circles/ovals
• Inheritance is shown with an arrow where the pointer is a triangle
• Links between items/kinds are shown with lines -- no arrow ends required because they're always bi-directional.

Examples

• Diagramming-content-models.jpg:
  

• Diagramming-attributes.jpg:
  

• Whiteboard-content-moAA549.JPG: