AI has fundamentally changed how software development works.
Yesterday’s software development process often looked like this: meet with customers, document requirements (a.k.a. a wishlist) as clearly as possible, transfer that knowledge to developers, write code, deploy, fix issues, and — if the budget allows — add tests at the end. Documentation? What documentation?
AI offers tools to reverse this flow for good — document, code, test, repeat.
Documentation becomes more than notes or static requirements. It becomes a clearly defined block diagram of the system — a structured representation of logic that is independent of language, whether human (English) or programming (PHP, C++, BASIC, Rust, or any other language chosen for the task). Tests and code are coming together. Iterations become faster and allow teams to catch flaws in logic, not just in code.
This session explores how modern teams can adapt their workflows to integrate AI tools responsibly and effectively into everyday development. We'll discuss the concepts of documentation-first software development and AI integration, then take a deeper dive into how you can use this approach to build a design system accessible to both AI and human consumers.
Image Credit https://www.productftw.com/productftw-3-the-tire-swing-cartoon
Nothing “mystical” happened between Step 1 and Step 2 - just a very typical loss of detail and context.
Why the Project Leader pictured it that way
They didn’t misunderstand that it’s a swing—they misunderstood how it should be attached and used. So they improvised:
-
“Attach to the tree” → interpreted as wrap rope around trunk (instead of hang from a branch)
-
No clarity on geometry → uneven ropes, awkward seat position
-
No clarity on use → built something that looks plausible but isn’t actually usable
This is what happens when someone fills gaps with assumptions under time pressure.
What likely happened between Step 1 → Step 2
-
Verbal, high-level description only
The customer probably said something like: “We need a simple swing on that tree.”
That leaves a lot open to interpretation.
-
No visual reference or sketch
A 10-second drawing would have eliminated 80% of ambiguity.
-
No clarification loop
The Project Leader didn’t ask:
-
“From a branch or the trunk?”
-
“One rope or two?”
-
“What does ‘simple’ mean here?”
-
Assumptions filled the gaps
Instead of confirming details, they substituted their own mental model.
-
Focus on “delivery,” not “intent”
The goal became produce something swing-like, not match the user’s experience.
What was missing in the customer’s explanation
Not volume—precision. Specifically:
-
Attachment point
“Hung from a horizontal branch, not the trunk”
-
Structure
“Two ropes, evenly spaced, flat seat”
-
Purpose / experience
“Comfortable, stable, safe to sit on”
-
Constraints
Height, weight capacity, materials, safety
-
Acceptance criteria
“A person can sit and swing back and forth smoothly”
The core issue
The customer described a concept. The Project Leader needed a specification. Customers usually describe intent, not implementation.
In box 10, the need is a simple, usable tire swing. But when explaining it, a customer often leaves out the details that feel “obvious” to them.
Why that happens
-
Curse of knowledge They can already picture the tire swing, so they assume others see the same thing.
-
Focus on outcome, not mechanics “I want a swing for relaxing” vs. “a tire hung from a branch at X height with one rope.”
-
They don’t think in specs Attachment method, balance, materials—those feel like your job, not theirs.
-
Over-simplification They reduce it to “a swing on a tree,” which strips away critical constraints
Nobody asked them to confirm: “Is this what you meant?” before moving on.
What was missing from their explanation
Not effort—explicitness:
-
Type: tire (not plank seat)
-
Attachment: single rope from a strong branch
-
Goal: simple, stable, easy to use
-
Constraints: safe height, minimal complexity
The customer didn’t “explain it wrong”—they explained it at the wrong level of detail. They made decision on the fly, and never documented requirements.
