Common words of the shared apocalypse

It's just a document

Imagine that we are building a software solution for managing scientific papers.

Each of the papers gets through various processes, some of them never get published, others are successful and become a state-of-art holy grail.

Of course, building software is vastly related to understanding the underlying "area of human activity" so that we can build models that work as solutions for the problems within that "domain".

So we went through some exploratory sessions with experts in the field - and seems like we understood the essential parts of the processes driving this business.

We have the "whys", we've heard about the vision, we know how we make money - pretty powerful drivers, I would say.

In one of follow-ups, the modeling session, there was such a conversation:

After such information exchange, two teams met and started figuring out the commonalities and then build services around them.

Soon, Documents API was created and started providing services for them all.

First release was a real blast. Developers, business people, architects - all celebrated this great success.

Configuration to the rescue

Things started getting a bit hairy with first few change requests.

Each of the teams pulled in its direction, trying to stretch this common service.

Coordination never ended and even small change required throwing a DACM - Document API Coordination Meeting - as it got named pretty quickly.

Massive amount of if statements, trying to cover the variabilities, followed up by the endlessly growing configuration, slowly started killing the velocity.

Soon, Documents API required highly skilled professionals who knew how to configure this beast.

It's generic, isn't it?

One of the core princinples of the Documents API configuration was its generic nature.

Documents Configuration API was created exactly for that purpose.

Whenever there was a crazy idea related to documents (it means either medical documents, financial invoices or scientific papers) - it got branded as "it's just a step in workflow and another configuration".

People started programming in a language called JSON, as it expressed Domain-Specific Languages of the Documents Configuration.

Soon, parsing DSON became one of the most desired skills in the company - where DSON stood for "Document Script Object Notation".

"He scared all his friends - learn this weird trick!"

There are certain words that bring havoc and fear to people's ambitions, motivations, and general well-being.

They might be regarded as harbingers of future pain that brings the highest mental damage.

I suppose both yours, dear Reader, and mine, dictionary contain much of similarly described words - in this tiny tale we are going to focus on four of them.

It's enough to destroy dreams and bury the happiness.

Let's start with three of them, as they fall into the similar category - generalizations.

"Shared", "common" and "generic" - three horsemen of the apocalypse

We all know them, we all love them - building something once and reusing everywhere - doesn't it sound blisfully?

Common models, shared code, generic solutions - mix and match all the permutations and you get nice input for buzzword bingo.

Those ones are pretty common (pun intended) to be found in architecture diagrams programmed in PowerPoint presentations.

Put some boxes and lines - everything ready, now it's just coding.

Donald Knuth once said:

It's of course tore out from its context - nevertheless we can use it for the purpose of this tale.

As you probably know dear Reader, I really like to nitpick words and play with the language - what could "premature optimization" mean?

What if this "premature optimization" points at "premature optimization for generalization"?

It like assuming that things can be reused because they look the same.

On diagrams and architectural sketches, everything looks marvelous.

But presentations and drawing on papers do not throw runtime errors or do not show compile time errors (can errors evolve? Check How do errors evolve?)

Typically "sameness" is defined on the attributes levels, structurally-wise.

If it looks like a duck, quacks like a duck, it must be a document. Oh sorry, a duck.

Also, this semantic diffusion moves meaning between the abstraction levels - how we represent certain concepts.

One of the origins of such thinking is focusing on data, not on entities, or not even on concepts (what's the difference? Please check Concepts, Entities, Data)

We tend to look for structure commonalities but we should move into thinking and observing communication structure commonalities.

This leads us into process thinking, looking at interactions and how certain concepts work together - not how they are related, hierarchy wise.

Still, this category of dreaded words is dangerous as we can pretty early start generalizing the common, generic solutions to distinct problems.

I like to say that each solution needs to prove its usefulness - eventually we might spot some commonalities and find out how we can generalize our solution to support more generic use cases.

Such support for other use cases might require us to generalize and/or abstract away the details - but yet again, abstracting does not mean generalizing (what do I mean by that? Please check The ambiguity of abstraction)

By prematurely generalizing we might start building enormous solutions for small problems we want to solve in the first place.

We will trap ourselves in big-bang planning, which always results in one thing: big-bang.

This involves complexity from every hole in our reasoning - as we plan to make common things, that will serve generic purposes which eventually become shared across many teams.

But now let's move the deadliest villain in the whole crew - in fact, everything starts from it and with it.

"It's just X" - ruthless and scariest horseman of the apocalypse

Imagine that you are brainstorming on a particular problem and someone throws the following statement:

• "it's just an if in the class Fluggaenkoecchicebolsen"
• "it's just another parameter in the constructor of Fluggaenkoecchicebolsen"
• "it's just a new bool property in Fluggaenkoecchicebolsen class"
• "it's just a new column in Fluggaenkoecchicebolsen table"
• "it's just about adding new attribute with the name Fluggaenkoecchicebolsen and it will work"
• etc.

All these have the same root - "it's just a".

It looks like I am really nitpicking on the language, but this little guy typically expresses carelessness in understanding the underlying problem we want to solve and immediately transitions us into thinking about the easy solution(s).

As we discussed that previously - Simple isn't easy.

"It's just a" dulls our vigilance.

It makes us vulnerable and susceptible to so many biases, mental shortcuts, and mistakes in thinking.

If things sound "just easy", fasten your seatbelts, turn on sixth-sense and observe the surroundings - possible proofless assumptions are being made!

Of course, one might say: "hey Damian, we don't have time to explore everything to start working".

Yup, that's true, but beware, because we always can rapidly build the wrong thing.

But no one said "everything" - there are certain concepts that drive the given area of human activity.

Those fundamental concepts are there, waiting to bloom and show their beauty.

"It's just a" don't let them grow, evolve and appear.

Everything stems from "it's just a" - including "shared", "common" and "generic" horsemen of the apocalypse.

This works almost like a dark magic spell, summoning The Horde of Deceiveful Assumptions.

Don't let the dark magic deceive you, dear Reader.

The cure for the poisonous thinking?

Ok, we revealed the despicable four words, and I hope you are not frightened, dear Reader.

Now we need to find something to counteract the consequences of those words.

Let's start with really obvious one - don't be afraid of playing with ideas - be brave and have a heart full of courage.

Not every idea needs to be implemented - by playing with ideas, brainstorming the possible options, we might eventually understand the problem more deeply and/or broadly.

Be open and put all the words - concepts - in the board (you can try to find out if they form Concept Maps).

There is no wrong answer, eventually you might end up with really elegant and simple solution.

And this requires iterations.

Growing.

Evolution.

Experiments.

Not every experiment needs to be implemented - it's all about breaking from "building the big castle" thinking.

Most of the experiments might bring discoveries - and it might lead to interesting observations and insights on what we are actually doing.

Of course, "concepts do not delivery value" - one might say.

In my mind, everything starts from the concepts and ends with the concepts - as we, human beings, operate in a world full of symbols we continuously create.

The winner is the one who has concepts that model a given area of human activity more efficiently, usefully, and evolvably.

And this model does not mean database model or data model.

It's above and beyond them.

So play with ideas. Iterate with understanding. Express it clearly and carefully.

Language is everything.