SharePoint Development from a Documentation Perspective
Now that I've told you how I create the technical illustrations I use in my blog entries and MSDN articles, I have a question for you:
Anybody got a decent notation for diagramming object models or XML schemas?
I've been looking around, and I don't really see any. As for what I'm using in my articles, well…I've pretty much been making it up as I go along.
Detailing discreet sections of a COM object model is fairly straight-forward. All you really have to keep track of are objects, members, events, and enumerations. But when I was trying to diagram how Donovan's OneNote SimpleImporter classes were structured, I wanted to include inheritance, as well as both public and private members (with appropriate scope noted). So I ended up with a legend that looked like this:
Take a look at the finished diagrams in this entry.
For the most part, this seems to have worked. But I have to think that someone else out there has tackled this problem. Someone with a lot more experience and talent in technical illustration.
I'm especially interested in how (or if) people are diagramming XML schemas. Here's the notation I used to diagram the OneNote SimpleImport XML schema:
But, as you can see, it gets pretty complicated pretty quick, even with a relatively short and straight-forward schema like SimpleImport:
Also, it doesn't show other schema information, such as the maximum/minimum times an element can/must appear. This information wasn't really important in this particular example, but I can see cases where it would be.
I hate that everything is in a grid, which makes it hard to read. I tried an alternate version of this, with shaded block rather than grid lines, but the results weren't any better. In fact, now that I look at it again, because I both indented the elements and separated them in boxes, I broke a basic rule of information design: I used two design schemes to denote the same information (the element hierarchy), thereby making the diagram more graphically complex than it needed to be.
That's the problem with producing content on a deadline. But I'm sure this won't be last time I need to diagram an XML schema for an article.
So, anybody got any better suggestions?