6 min read

Thing explainer: Complicated stuff in simple words

Thing explainer: Complicated stuff in simple words
Photo by Patrick Tomasso / Unsplash

You may wonder why I am using the title of the book for a blog post. Is this a review? Not per se, but it is a good basis for a catchy title and the topic I wanna touch upon. And I believe Randall Munroe wrote an interesting piece that showcases how even the most complicated of things out there can be broken down into simple language. That everyone is using and can understand. Or at least enable them to follow along.

Age, when developers were closely kept behind some locked door in the basement, is slowly but surely over. We're expected to interact in the real world. With real people. Who absolutely have no idea what are we talking about. In most cases. Even we get confused sometimes, so can't blame them. We try solving this by putting some kind of a middle layer, a translator of sorts, between us and the normies. You will recognize them by a title or by dressing up in something more than Star Wars t-shirts. Their job description will have something along the line: Dealing with stakeholders. Probably their first job is to explain what in hell is the stakeholder.

Anywho, more often than not, we're in the same meetings (some of us wearing sarcastic t-shirts) with those same confused people. Both parties look at each other while trying to find that common language. That goes beyond the first 10 minutes of the meeting and: "Hello, my name is ...". Here is where, as developers, we start getting exposed to a domain of the problem within whose border we're working. We're confused, maybe even more in some cases, than people sitting opposite of us. Where we try to map whatever is being said to things like design patterns, classes, interfaces, methods, etc. And often, more than not, failing. At least for the first x-number of "refactorings". And to add to the overall confusion, we spat out those terms and we need the same meeting in a couple of days, again.

Then, due sheer frustration this causes, we turn to books. And internet. Mostly as when we think we understood a subject and tried to explain it by drawing UML on the board, we figured out we didn't. Ok, nice drawing, but what is this thing you call class with the name UserAbstractFactoryProducer? So many layers in a simple question. Of two worlds colliding. And, as mentioned, we look into the books. And we discover things like Domain Driven Design. And we try defining roles from it, for example, Domain Experts. So no longer a stakeholder. Now he is someone that can tell us how the domain works. And ubiquitous language. Tong twister that one, right? And things just spiral out of control further...

Don't get me wrong, I do believe that Eric Evans wrote a good book. That is trying to teach us a valuable lesson. How to have a conversation while keeping the discussion (and our UML) more human-friendly. Or on the side of that Domain Expert, we're having a conversation with. Or at least, that is what I believe, he tried to achieve. Reality and the number of confused code bases thought out my career, showed me that is not working out. Failures in clear communication between the two people in the same room are now translated into more equally confusing code. There are a number of reasons for this, or at least what I saw and believe to be so.

Let us go from the book. It is a dry read. It requires a lot of concentration and will to go through the entire book. Next to that, it introduces a number of new concepts, some of which are mentioned above already. To teach how to streamline communication in the domain terms. And how to write your code to reflect the same. When you mix all this, plus how we interpret what we read... Well, let us say it can lead to some interesting discussions. The same goes for any other concept, don't get me wrong, but here I am mostly talking about this particular software design approach. An example that I see quoted the most when it comes to "How to talk to your stakeholders". I do see the merits of it (and similar design approaches), which can lead to cleaner communication with stakeholders. As with most things, it does require practice and constant refinement. It is not just developers who will need clarification and catching up, it is the people for whom we're developing solutions. And again, we made a circle back to the problem we were trying to solve. Ok, Einstein, then what is the solution?

One of the reasons I started this by mentioning a Thing explainer book is that I believe this is the key. Or the idea conveyed within it. Being able, without introducing any new terminology or roles, to distill down your understanding of the problem on the same level (or at least close to it) as the person you're talking with. Hard thing to do and requires you to learn (actually learn) about the domain you're gonna be working within. Believe me, it is a hard thing to do. And usually, time limitations require some "extra" time which is never there. It requires asking a lot of questions and paying attention. Really paying attention, like you're going to be replacing that person. One of the terms I do love from the Domain Driven Design that is applicable in any methodology (or better say it should be), is the term Glossary. It is part of the book where discussion around Ubiquitous language. Simple concept really. Build a dictionary of the language business uses to describe something. And when you have a clear definition, it just takes time to go back to it, every time, when this pops up. Eventually will become muscle memory.

One thing that helps me, is trying to come up with analogies when I have a hard time conveying my thoughts to others. Or understanding theirs. Trying to find an example, from the real world, that both parties can relate to. It is a simple tool, that really can act as a medium, until we're both on the same page. Afterward, everything that was causing confusion should be nicely documented. Feature by feature like this and you're on the way to becoming somewhat of a Domain Expert yourself.

So my process, which I am trying so many words to describe is not to start with terms from my world. But trying at least to understand the one from people that they're familiar with. Document it, and as I am a visual person that means diagrams. All the terms used within this documentation should be referenced in the glossary, with a clear and unambiguous explanation. After that comes the translation of those terms in the code. Depending on the team, this could mean using DDD. Or not. It is up to you and the team to define, what is the translator between the implementation and how to communicate it. The silver bullet doesn't exist.

Documentation can't be underestimated, in my opinion. And documentation that targets different stakeholders in a language that they use will save you days that you won't need to spend in meetings. Wait, what do you mean by 'documentation for different stakeholders'?? As we have a way to explain our architecture in code, I strongly believe that not all documentation communicates the intent in the same manner to everyone involved in the project. Use UML for a software architect to explain the integrations and models. And a flowchart you would use to explain the same thing to a stakeholder. They're interested in different things, so document your features according to who is the intended target. And message you want to get over. It does lead to maybe documentation hell and extra cognitive load, but on the other hand, there is a number of tools out there that can help you with this. There is a correlation between how I believe this should be done, so let me try to illustrate it with a picture.

documentation levels

Hopefully, this makes it somewhat clear, what I mean is that we need to have different layers of documentation depicting, in the end, the same thing. Technical documentation is also stakeholder documentation. It is just that stakeholder here can mean: other development teams, architects, etc. Documentation for stakeholders is like JSON for POCO. A more readable version of the same documentation. And all of them should be based on and reference the glossary and agreed-on terminology.

Ok, so let us close up. After more than 1500 words, the point I was trying to make is: Documentation on projects is necessary. What makes documentation effective and not just another thing to maintain:

  1. Domain knowledge: There is no way around it. It is not just a technical term to be thrown around. You need to start understanding the domain you're working within and be able to understand how to communicate effectively in it.
  2. Clear language: We need to immerse ourselves in the domain we're trying to solve and communicate in the same manner as our stakeholders.
  3. Targeted: Write documentation based on the needs of your stakeholders. Those can be technical or business. Tailor it to address the Q&A question they have around implementation.
  4. Glossary: All the terms used in documentation should be defined in a single commonplace. It should be business/stakeholder-driven, not technical in nature. Use it as a reference when writing documentation, so that everyone is on the same page when some "unfamiliar" topics come up.

In the coming topics, I will touch upon "self-documenting" code and some other myths.

Until next time, my dear Domain Experts.