The ambiguity of state: facts, interpretations and perspectives

Oh no, sick kids!

Imagine that there two parents: Karen and John.

They have two kids: Alice and Dylan.

The life was good, until one day when both got back from the school and had strange symptoms: vomitting, fatigue, diarrhea, and fever.

Well, not a pleasent situation for the kids.

And even more unpleasant for the parents, who had to deal with the sudden illness of their children (and in general with the situation at home).

What did the parents do in this situation?

Called the doctor, immediately.

Also what they did, before the doctor arrived, was to make sure the kids drank plenty of fluids.

But there was another problem which was not known from the beginning - whenever any of the children drank any fluid in a glass-volume amount that was too large, they would immediately vomit it back up.

This complicated the situation.

The doctor, Mrs. Ivonne, examined the kids, listened to what parents ellaborated about the situation.

She then diagnosed them with a strange viral infection.

The doctor was pretty knowledgable and she know it's good to visualize the knowledge, even for a simple case like this.

She wrote the rules on the piece of paper and handed it to the parents, ensuring they are all aligned - to achieve so, she asked both parents to explain her how they would administer the dosages.

Instructions from the doctor (generated with LLM)

Even though the situation was really challenging, both parents were happy - they got pretty detailed instructions from the doctor on how to care for their sick children.

Now it was a matter of living through this sickness, with some disciplined administration.

Parents + Engineering = ...?

Karen and John wanted to approach this a little bit more structured and organized, applying some engineering principles to ensure they followed the doctor's instructions accurately.

Fortunately, they had a whiteboard where they could keep all the information in the single, central place.

Such that they won't administer something incorrectly, just by referring to the whiteboard for guidance.

They divided the whiteboard into two halves: one for Alice and the other for Dylan.

Whiteboard as a central place for keeping all the information about kids. (generated with LLM)

Now, they needed to think a bit about how to organize the information, so that they can quickly find the relevant details when needed and avoid any mistakes in administering the medications.

Parents decided to devide everything into categories based on the discussion with the doctor: temperature, vomitting, hydration, meds.

Additionally, they thought maybe "notes" as a separate category might be useful to have - having more information sounds better, isn't it?

Whiteboard structured into categories for each child. (generated with LLM)

When they stood in front of the whiteboard, they felt proud of approaching the whole experience in this way.

Whiteboard-driven sickness management

The life was moving on and both parents were diligently following the structured approach they had set up on the whiteboard, ensuring that their children received the care they needed.

Everything was meticulously recorded and updated on the whiteboard, providing a clear and organized view of the children's health status at any given moment.

Whiteboard updated with the latest information about the children's health. (generated with LLM)

It looked both impressive, but also a bit...Messy?

It was definitely possible to read the state of each child's health and how does a recovery process is progressing, even if the whiteboard appeared a bit chaotic at first glance.

Problems started araising when Mrs. Ivonne asked about a specific detail regarding one of the children's medications, and it took a moment to locate the information on the whiteboard.

Additionally, she queries for a summary of last days which required juggling TEMP, VOMIT, HYDRATION, and MEDS sections on the whiteboard, making it a bit challenging to quickly compile the information.

The nail to the coffin came when the doctor came back with a conclusion that the fever temperature threshold over which a medicine needed to be administered was different from what she initially said.

Mrs. Ivonne spoke with the lab and they clarified that this virus requires more careful treatment so the rule for dosing the medication for fever was not using 40°C as the threshold, but rather 38°C.

This meant that all the previous entries on the whiteboard regarding fever and medication needed to be re-evaluated and updated according to the new threshold of 38°C, adding to the complexity and potential for confusion.

Karen and John organized the whiteboard around the information, not about "real" facts they observed while taking care of their children.

Even though is seemed structured and organized, as the time passed, it was a bit rigid and less adaptable.

Constraints liberate, liberations constrain?

They became aware that what they are dealing with is not just a set of information with relationships, but rather a process - something that flows, expands and contracts.

They still wanted to use the whiteboard as a tool for keeping the information, but this time the information they will gather and interpret is going to be different.

Karen suggested to focus on what is happening, rather what is changing.

This meant paying attention to facts, rather than mere information.

Also, what they learned from the whiteboard experience so far is that it's very tempting to erase information or update information, because it seemed easy.

Some of the entries from earlier got buried under other information, which basically made parents lose important insights about the progression of their children's health and recovery.

The decision was made - entries cannot be erased or overwritten; instead new entries would be added to reflect the ongoing changes and observations, creating a chronological record of the children's health and recovery process.

This single constraint fundamentally changed how they interacted with the whiteboard.

To achieve such constraint, John suggested using orange sticky notes so that they can treat each entry as unchangeable once it is added.

Stickies representing the record of what happened when during the recovery process (generated with LLM)

After they established another way of organizing the information on the whiteboard, they started thinking what kind of facts they need to capture and keep track of.

They realized that capturing facts required a clear distinction between observations and interpretations. Observations are direct, verifiable occurrences, while interpretations are the meanings or conclusions drawn from those observations.

This distinction helped them understand that while observations could be recorded as immutable entries on the whiteboard, interpretations could be added as separate entries that provide use case and insight without altering the original facts.

So they came up with the following list of facts that were important in their situation:

• "Temperature measured" with details:
  • which child
  • when measurement was captured
  • the measured temperature value
  • who measured the temperature
  • what device was used (they figured out that they used either a digital thermometer or an infrared thermometer)
• "Vomited with fluid" with details:
  • which child
  • when it happened
  • the volume of vomit (small, medium, large)
  • who observed it
• "Vomited with food" with details:
  • which child
  • when it happened
  • what food was vomited (if known)
  • the volume of vomit (small, medium, large)
  • who observed it
• "Fluids offered" with details:
  • which child
  • when it was offered
  • what type of fluid was offered (e.g., water, juice, electrolyte solution)
  • the volume of fluid offered (spoon, glass, bottle)
  • who offered it
• "Fluids consumed" with details:
  • which child
  • when it was consumed
  • what type of fluid was consumed (e.g., water, juice, electrolyte solution)
  • the volume of fluid consumed (spoon, glass, bottle)
  • who observed it
• "Fluids refused" with details:
  • which child
  • when it was refused
  • what type of fluid was refused (e.g., water, juice, electrolyte solution)
  • the volume of fluid refused (spoon, glass, bottle)
• "Dose administered" with details:
  • which child
  • when it was administered
  • what medication was given
  • the dosage
  • who administered it
• "Urinated" with details:
  • which child
  • when it happened
  • the volume of urine (small, medium, large)
  • who observed it

Karen reviewed the important facts they considered as essential and additionally suggested the following:

• "Symptom observed" with details:
  • which child
  • when it was observed
  • what symptom was observed (e.g. "fatigue")
  • who observed it
• "Slept" with details:
  • which child
  • when it happened
  • the duration of sleep
  • any wake periods during sleep
  • who observed it

John was very happy that they focused on what they must observe during the care of the children.

Somehow it felt "right" from the start of using this way, because they didn't need to focus on the structure of potential, future interpretations, like this inquiry from the doctor about the summary, or anticipating what they need to count.

By doing that, they were able to separate observations from interpretations.

He also highlighted that there is another important fact to consider: issuing instructions.

They received instructions and initially Mrs. Ivonne told them to use 40°C temperature as the threshold for administering medication.

Then, the rule changed and 38°C was the new threshold.

So additionally to previous meaningful observations-to-record, they decided to add one more:

• "Care instructions received" with details:
  • which child
  • when it was received
  • what the instruction was
  • who issued it
  • when it was effective from

In case of changes to care instructions, they will be able to adjust how to make the decision regarding administering medication or other care actions accordingly.

After some time, that is how the whiteboard looked, filled with all the essential observations they captured:

Children's health observations (generated with LLM)

They were able to use those facts to make decisions about next steps, when it came to assisting in the recovery process - whenever vomit occurred, the additional medicine should be administered (according to the care instructions received).

According to the rules, three vomits in a 5 minute window, under a fever threshold, triggers giving the medicine.

Parents could easily retrieve such information, just by going through all facts recorded on the whiteboard, for the kid who vomited.

The doctor calls to check the child's condition based on some summary information?

Sure thing - just start from the left side of the kid's whiteboard-half and follow the sequence of observations recorded there, creating the summary.

Finally, Karen and John felt empowered by all the optionality offered by those facts, represented by stickies.

Previous approach was not bad and not evil, on its own.

It was not yielding the same level of options and flexibility, when it comes to adjusting based on the evolving situation.

And the most important constraint - no erasing and no overwriting of existing observations on the whiteboard - truly guided their behavior.

The process of healing?

One day Mrs. Ivonne called them to check what is the situation right now.

She told them how to take care of the children, but she was not clear on specifying when a child could be considered fully recovered.

The doctor expressed the following: "whenever any of the following happen: fluid was consumed, temperature was measured, a child urinated, perform a check - full glass consumed, temperature below threshold, child has urinated - all in 2 hours, then recovery can be considered as completed."

Soon, John used this guidance to verify the state of the recovery process of both kids.

Finally, both Alice and Dylan were considered fully recovered according to the doctor's criteria.

The model of everything?

Both parents fall in love with this approach for organizing "things" - even though it might have seem as overly complex and difficult to follow at first, they quickly realized the benefits it brought in terms of clarity, accountability, and flexibility in managing the children's care.

It turned out it's not only for managing the children's care - but it fits other problems too.

One day, John noticed that Karen appended a new sticky note to the whiteboard, in Alice's half.

It caught John's attention because it contained the following information:

• "School project scheduled" with details:
  • what is the school subject
  • what is the topic of the project
  • due date
  • required materials
  • when it was scheduled

It was definitely worthy having such fact recorded, but at the same time it did not feel "right".

"So far, we were keeping observations about recovery process, and this new one is more about school-related activities?", thought John.

He decided to leave it for now and see how it would evolve.

Sick kids? Vomitting? Diarrhea?

"Ok Damian, what the hell did just happen?", one could definitely ask angrily.

People are serious software professionals and I dare to tell a tale about sick kids, vomitting and parenting?

How disappointing it might seem to be!

But wait, let's stop here and ask one important question.

Do you know what this tale was about, dear Reader?

Probably you have already guessed.

We saw event sourcing in action, but more on the conceptual level.

Our whiteboard played a role of persistent storage, initially acting as "a general storage".

All the observations were events, capturing what happened over time.

Both parents played the role of "consistency boundaries", ensuring that proper decisions are made based on the rules driving this "tiny, toy domain".

They both were "deciders", using models for deciding - very specifically built ones, out of all facts that happened, but applying one by one until the correct set of information was obtained.

Throughout this tiny tale, we saw how parents were trying two approaches to managing the complexity of the situation.

Initially, they used structured approach for capturing snapshots of the state.

So it's not that they did not put any effort in analyzing and planning the way of organizing.

They represented information about each children, using categories they understood and found relevant for tracking the recovery process.

It was easy to start, but the more into the future, the harder it was to maintain consistency, especially when the requirements changed - new rules arrived, new inqueries appeared.

What could have mislead them was the assumption that they are facing a state of sickness of each kid, rather than a dynamic, flowing process that evolves over time.

One could say that they focused on nouns, without checking how these nouns interact with each other, transform over time and form a flow of "work" (=a workflow).

They might have fallen into "a nominalization trap".

So telling a story how they arrived at certain state was challenging, but not impossible.

When they realized they are dealing not with "a state of sickness", but rather with a recovery process that unfolds over time, they adjusted their approach accordingly.

They switched into looking at important and meaningful facts that they could and needed to observe over time.

And there was no magic - parents needed to spend time to carefully analyze, structure and organize those facts-to-capture.

The quality of that process helped them gain a clearer understanding of the recovery journey and make informed decisions along the way.

Even though "the requirements" changed, like those instructions from the doctor, the approach was accomodating them quite easily, because parents were observant and skilled enough in defining the process.

They were able to adjust the way they interpreted the captured facts, depending on the evolving context and the specific needs of each moment.

And this "one simple trick" changes almost everything - separating facts from ways of interpreting them is so enormously powerful.

What does it teach us, dear Reader?

Facts? Interpretations? Perspectives?

Look around, dear Reader.

Our mind constantly interprets the facts happening in the external world (external to "us"), tricking us into believing that each "thing" in the surrounding environment is fixed, static.

A spoon that was placed in the pot of boiling water, and started heating up, might seem like "the thing", but in reality, it is part of a continuous process of heating and cooling.

Continously flowing.

Panta rhei - everything flows, nothing stands still.

But it is just one process - thermodynamical one.

And there are other processes to - manufacturing process, selling process, delivery process, claiming process, and so on.

So a single "thing" can be a subject of many, different flows.

That's why we, as software professionals, need to pay attention to dimensions while we are analyzing, reasoning and designing systems.

An avid Reader might realize that "there is no spoon", at least not the spoon.

There are many spoons-in-different-contexts, each undergoing various processes, and it's our decision what is relevant, important and worth modelling.

One could say a spoon might be viewed from different perspectives.

And we already know that mixing different perspectives into "the single thing" might create problems in the near future.

This absolutism-attracting force, "the knowledge gravity" as I like to call it, will lead to another trap related to state - mistaking the current snapshot, needed in a given use case, as the state of a given "thing".

The same nature was possible to be observed in the context of children recovery process, that Karen and John experienced.

Initially, they focused on dealing with sickness and recovery facts, but as soon as Karen noticed another important fact - "school project scheduled" - she needed to assign it somewhere.

Unfortunately, they named the whiteboard-halves after their children names, immediately anchoring themselves into thinking in "absolutisms".

Naming is framing, so this "single, tiny event", related to the school, might have started the process of entropical information attraction.

Started with recovery concepts, this stream of facts might slowly, but steadily, acquire more concepts related to school, social life, and other aspects of the children's daily activities.

And sooner or later, various perspectives will make the entire event stream:

• hard to maintain due to its length and coupling
• hard to ensure consistency due to overbloated consistency boundary
• hard to perform well due to its length
• and more

That's why event sourcing might not help us if we incorrectly organize event streams, decomposing them along incorrect boundaries.

This means that just capturing events is not enough - one must use use calories to explore, discover and establish boundaries, watching out for the Diaper effect.

The state of designing systems?

It's easy to fall into a common trap of looking at absolute concepts, as well as focusing on the current snapshot of the system's state.

Easy, because it requires little effort to grab what is immediately visible, without paying attention to depth, perspectives and time.

System 1 kicks in so blazingly fast that the judgment is done before noticing it's all over.

That's why we need to slow down and use quality time to collaborate with others to align and avoid hasty conclusions.

"Haste makes waste" which might not be initially visible.

So next time dear Reader, look for what happens when it comes to what you are analyzing and observing - whether this is a manufacturing process of a spoon, a child's recovery journey, or the evolution of a software system - all in specific contexts (here: perspectives).

This framing is so powerful that influences the system architecture in a great extent, because of the used language.

And this language frames our thinking, either limiting or opening possibilities.

If we start naming things in the context of "continously flowing", this would be the world we see.

If on the other hand we decide to name things as absolute, static entities, this would be the world we operate in.

So next time dear Reader, when you are presented with a business problem or an engineering challenge, ask yourself:

And remember pay attention to the language and start naming various perspectives you and users might look at this workflow: