Over the past week or so I’ve been revisiting an old project with @walkah — an extremely complicated domain model with piles of wild business rules, and an interesting mix of component content that gets assembled (and some values calculated) based on the inter-connections.
The very first iteration was one I cobbled together with spit, baling wire, and layers of patches in 2016 or so. @walkah and I are taking a new approach, and it’s been exciting! We started trying to use diagrams, but…
…We quickly discovered that the clarity a good diagram brings can be compromised when the relationships are complex enough and the granularity of the components is fine enough. So we started again with a Vocabulary and Grammar based approach.
Rather than visualizing connections we’ve started by writing clear (as possible)short definitions for every important term in the domain. Organizing them in terms of specificity (A means blah; B, C, and D are special kinds of A with these additional meaning) etc.
We’re not all the way through but so far it has been much more effective than the usual approach I’ve taken with content whose relationships tend to be simple “composition or connection” oriented.
None of this is new to someone from the domain driven design camp, but it’s been a great exercise. While we’re definitely going to be hammering out some visual diagrams to clarify interactions, the underlying vocab will take a lot of pressure off of those visualizations.
Emphasizing the domain vocabulary first is also helping us avoid the mistake I made in my '16 version of the system — warping the key terms around the choices made to implement the model in a particular technical framework.