· 2 min read
Take a history before you write code
Medicine taught me that the presenting complaint is rarely the diagnosis. The same is true of software briefs. A five-step clinical method for building the right thing.
In clinical training you learn, very early, that the patient’s first sentence is not the diagnosis. “I have a headache” could mean a dozen things. The doctor’s job is to take a history: when it started, what makes it worse, what was tried, what else is going on. Only then do you examine, and only then do you prescribe.
Software briefs work the same way. “We need a new website” is a presenting complaint. Over time I have turned that habit into a method I use on every project.
01 · History: listen first
Before proposing anything, I ask questions:
- Who is this for, and what do they need to do or believe after visiting?
- What has already been tried, and what happened?
- What does success look like in numbers a year from now?
- What are you afraid of?
That last question is the one people don’t expect, and it is often the most useful. A fit-out company is afraid of being seen as unreliable. A founder is afraid of building something nobody uses. Fears point straight at what the product must prove.
02 · Examination: look before you prescribe
Then I examine the current state: the existing site, its analytics, its speed, its accessibility, the sales conversations, the questions customers ask on WhatsApp. In e-commerce, it means reading the conversations behind refused orders. The examination often contradicts the history, and the contradiction is where the insight lives.
03 · Diagnosis: name the real problem in one sentence
A good diagnosis fits in a sentence. “Refused cash-on-delivery orders are a trust problem, not a shipping problem.” “Clients can’t find proof of their kind of project.” “The study is too big for a poster.” If I can’t write the sentence, I am not ready to build.
04 · Treatment: the smallest dose that works
Medicine is cautious about dosage for a reason. In software, the smallest effective change ships sooner, costs less and teaches you more. For my own store, the treatment was four automated messages, not a new platform. The platform came later, once the dose had proven itself.
05 · Follow-up: measure and stay reachable
Treatment without follow-up is guessing. After launch I measure the thing we diagnosed: delivery rate, enquiries per visitor, time to first reply. And I stay reachable, because the first weeks after launch are when the real symptoms appear.
Why this works
The method slows the first week down and speeds everything after it up. Clients feel heard, because they are. Scope stays honest, because it is tied to a diagnosis. And when someone later asks “why did we build it this way?”, the answer is written down in a sentence.
You don’t need a medical degree to use it. You only need the discipline to keep your hands off the keyboard until you understand the person you are building for.
Keep reading
· 2 min read
Why the AI in nqrah never writes code
Atelier designs whole stores from a sentence, but it composes from a library of 31 tested sections instead of generating HTML. That constraint is the feature.
· 2 min read
Research communication is a design problem
For our energy-drinks study I designed the presentation, the poster and the website as one system. What I learned about making research readable, citable and accessible.
· 2 min read
Every behaviour has a reason: what psychiatry teaches product builders
A customer who refuses a parcel, a user who abandons a form, a merchant who never logs in again. None of them are irrational. They are telling you something.