Building Bridges – Communicating Complexity
Over the years, I've built a lot of technology at DashKite. And while that's been a richly rewarding experience, technology is only valuable insomuch as people can understand and apply it purposefully. I haven't prioritized explaining myself. I feel a sort of self-conscious about trying to convince someone that I can do something instead of just doing it. But the time has come to reprioritize, to start showing my work.
Photo Credit: Alex Azabache
Unfortunately, explaining myself — even to audiences predisposed to believing me — has met with mixed results. Dan and I have come to realize it's a problem related to complexity. We've spent years learning about the patterns involved in our technology, we've gotten used to how each other thinks, and we've even developed a proto-vocabulary to speed conversation. Talking to someone without that shared context makes the transmission of ideas difficult.
That got me thinking about the nature of our context and how its complexity is symmetric to the software we've built. It's a bootstrapping problem even to establish a vocabulary, and we cannot fit years' worth of learning into a single conversation. But thanks to that symmetry, we can address the context problem in the same way as our software.
This blog post marks a new era for DashKite. In the coming weeks, I will thoroughly document the low-level libraries that make up the DashKite stack. That forms a reference layer. Then, we need to write a layer that describes individual concepts. On top of that, we explain how tooling and architectures work. And then we're ready for high-level narrative overviews.
It's a fair amount of work, but it's vital. Almost worse than being ignored is being misunderstood. The adoption history of REST architectures provides an excellent example of this costly failure mode. Roy Fielding defined REST in a Ph.D. dissertation and codified it in the HTTP specification he helped author. Unfortunately, people write those for very particular audiences; neither are a very good starting place for shared context.
The key is meeting people in their software journey. Hypertext lets us focus on one thing at a time, stay DRY, and put people first by supporting self-directed learning. It's comprehensive, but it doesn't leave people stranded with reference docs. It's engaging, but it doesn't lack precision when you need to look something up.
Not only is this an efficient way to communicate a complex concept asynchronously, but it also reflects our software patterns. So in that way, it reminds me of Conway's Law.
Time to get writing.