We were deep into building a new microservice — one of those projects where the requirements were abstract, shifting, and open to interpretation. You know how it goes: "It's just a simple microservice, basically it should just save X and communicate Y back". Yeah, right...
At first, it felt manageable. Everyone, including me, nodded along in meetings. But slowly, assumptions started to differ. One teammate thought of the flow one way, someone else committed their understanding of data model, then we discovered some corner cases and new requirements popped up and then there were conflicting requirements and so on...
By the time we were halfway through implementation, we realized we weren’t building the same thing. We weren’t even on the same map. How it should even work?
So I did something simple, yet useful.
I drew a flow diagram. Just boxes and arrows. Good old draw.io. Exported it to a PNG and shared it with the team.
That one diagram turned into our anchor, that single source of truth we didn't had before.
We reviewed it with the team and the business people. For the first time, everyone saw the same picture (pun intended). From that point on, it became the go-to reference for everything – requirements, scope clarification, even naming decisions.
Suddenly, we were able to:
- Add meaningful tickets to Jira
- Update the DB model based on real scenarios
- Point to specific parts of the diagram and say, “What happens here?”
- Make decisions faster and with more confidence
It was like handing out a map in the middle of unfamiliar city. People stopped guessing where they were and started moving in the same direction.
The Lesson (Re-)Learned
If things feel vague, confusing, or open to misinterpretation – draw something. Even a napkin doodle can go a long way. A visual representation of a process or system can align people faster than 10 Jira tickets with a single sentence of "acceptance criteria" or the 10th recurring Teams call this week.
It doesn’t even have to be pretty, or follow UML rules. It just has to exist.
Who knows what we would’ve ended up building without that diagram?..
