I spent many years teaching for Learning Tree International, New Horizons, and privately. That has given me a very formal perspective on presenting complex material that isn’t yet understood to people who are much smarter than I am.
I’ve also created an enormous number of models and diagrams over the years to present to clients. And I’ve been in the meetings when others present their diagram sets as well.
Having made the mistakes, watched the mistakes, and sometimes even avoided the mistakes, there’s a very basic trap that I want to spare all my fellow modelers and diagram authors — and it’s one I see still at all levels of organizations.
The trap is this: showing the big picture first.
I understand that you should “tell them what you’re going to say, say it, and tell them what you said.” Perhaps. But if you show a complex diagram (more than two or three boxes) that you expect to explain in detail, it’s only going to go downhill from there.
I have made a few extensions and Domain Specific Languages (DSLs) to represent state machines.
Some were frameworks in a native language, including versions using the State Chart pattern. One was in C++ integrated with an event and entity framework so that entities could participate in threaded declarative workflows assembled instead of derived.
But the ones I enjoyed most were done in Lisp. The simplest was a sexpr based notation that was read by clisp and emitted Java. It was, of course, a macro. The expression of the machine was executable and the execution was to emit Java. It generated interfaces, abstract base classes, 100% of the POJO that represented the messages, and required no fences — it was a full code generator, not a wizard (no generated code was edited by hand or saved in the version control system).
I did another recently. This time, I decided to tackle the interesting problem: state machines become unbearably big and repetitive if done following the conventional model.
So I decided to toss the rules aside.
I’ve a few friends that are writing novels. I spent a few months banging on what I call a “bad fanfiction” following a bit of advice I read from some professional book on writing fiction. Since it’s not mine (I don’t own the IP, yeah, I’m still a tech guy) I won’t publish it, but it was (and still is, from time to time) really amazing. I have 260,000 words into it, for instance.
And most of them, all but about 250 I think, are junk. So, 259,750 words are garbage. That’s the math.
Those who have read my blog know that I’m a software developer more than a writer. But I discovered that there are many facets that are the same and oddly, some skills that work well in both.