I’d Really Like To Draw A Picture…
August 2nd, 2008
I’d like to draw a picture—I really would. It wouldn’t exactly be an entity-relationship diagram, or a database schema, but it would combine elements of both, and it would help me explain the model underlying the app I’m currently working on to the whole team (myself included). But I’m not going to bother, because experience has taught me that it will cost too much to maintain:
- There isn’t a decent lightweight open source cross-platform drawing tool for this kind of thing: Inkscape and Dia just don’t measure up to Visio and Omnigraffle.
- There aren’t tools to check those diagrams against actual schemas, or vice versa. Well, OK, there are, but all the ones I have found can only check drawings they’ve created (i.e., they conflate drawing with checking), and none of them talk directly to ORM code like SQLAlchemy or Hibernate.
- Most importantly, version control systems don’t know how to handle diagrams, even ones stored in SVG or other pseudo-text-based formats. I want “svn diff” to be able to tell me what’s change between the last version of the diagram and this one; I hate launching two versions of a drawing application side by side and playing “spot the change”. I want merge, too — if Jeff and I are both working on a complex design, I don’t want our tools to make the job even more complex.
So here I am, doodling in my notebook instead of creating something I can actually share with my fellow developers. Pfah.
Try Graphviz (http://www.graphviz.org/). It’s text based so this solves your svn diff problem. You could write a small translator to parse your data structures and output the dot syntax for graphviz (it’s simple) and that solves your diagram going out of date problem (just add it to make I guess). It’s automated drawing.
I don’t want to sound too confident about it, I’ve only played with it — I haven’t worked on a project yet that required what I described above, but I believe from the tests I’ve done that it would work. Check it out
You could (as I have done in the past); sketch it on A3, (thats like two sheets of ‘letter’ for those who don’t know); date it; scan it; present it.
I gained too much from having a diagram to discuss, over knowing that it would be hard to maintain.
At least with the date on it it’s some you know when it was meant to be accurate
- Paddy.
P.S. their are supposed to be programs that can turn hand-drawn line drawings into something neater, but I didn’t look.
If your framework/language lets you implement your basic database structure and relationships between objects quickly and easily, then one approach which works well is to introspect or parse your code and hence generate a .dot file for rendering with GraphViz. I am thinking here of the RailRoad gem http://railroad.rubyforge.org/ which does this for Ruby on Rails applications. Check out some of the example diagrams towards the bottom of that page, I think they are along the lines of what you are wishing for.
While not trivial, it should not be unduly time-consuming to develop a similar tool for any framework with good ORM abstraction. Obviously because the relationship graph is derived from live code, it will always be up to date. Especially if you have, say, a pre-commit hook which updates the diagram automatically.