Ask better questions

Can you implement a sign up flow?
— my client

Those are the kind of request I was happy to receive. It's a straightforward, basic concept with a ton of best practices available to view online (it was 2023, can't ask Claude). Present a sign up page, attach Cloudflare Turnstile↗ (opens in a new tab), request email confirmation, and you're basically done. I wouldn't have to spend half a day figuring out what the request meant.

I prepared a draft note before talking to the client's technical stakeholder. I had implemented registration before, so I asked questions I already knew the answer. What fields did they need, should users confirm their email, is there any rules for password, that sorta stuff.

Those answers were enough for me to start coding, which was conveniently where I wanted the conversation to go. We ended up spent less than a day implementing and testing that feature.

Complications#

The day after, they asked if the flow included a "KYC" for organizational verification. It came out of nowhere for me, really. I rushed to check my functional & technical specification documents scribble notes, worrying whether I missed something. Turns out I was right and shipped the feature as requested.

Just when I was about to clarify the issue with them, their team poked me again for a meeting in their office. That meeting is they basically telling me that I misunderstood their request, and the correct sign up behavior is the application should include an initial sign up payment in order to use the app.

At one point I asked whether the verification happened before or after sign up. They asked what I meant by sign up.

Well, you fill in the form, confirm your email, and now you have an account.

Apparently, they considered the organization signed up when it was approved and could actually use the application. I had been explaining how to create a user while they were thinking about onboarding a paying organization. Nobody thought to check what the other person meant, because come on, who needs to explain what sign up means?

Well, me, apparently...

A little crisis#

I walked out of the meeting room frustrated as hell. Now what do you mean a simple request grows into an enterprise IT team's whole week of work? I regrouped with my teammates to discuss our implementation plan. We then decided to take a step back and re-analyzes their business requirements. Realization does come late, and for us it's right at this moment.

We drafted a requirements doc (a real document for once) based on whatever notes we scribbled during meetings or best practices that we can follow. We spent half of a working day working in a shared Google docs, in rush, because we didn't want to spend anymore time thinking about that abomination of system design.

We finished the document later that evening and sent the link to our client.

Before I slept, I got an email from Google telling me that there was new comments on the docs, but I'm too tired to lift my phone.

One of the comments asked what would happen if an organization paid and then failed verification. I scrolled back up to our payment section, then down to verification, hoping we had already written something useful. We hadn't.

We had described both features in enough detail to start implementing them, but we hadn't agreed on which should happen first. I was already imagining another meeting, which was exactly what I had hoped this document would save us from.

In the next call, we asked them to walk us through how they would onboard one organization. Whenever we got to something like "then we approve them," we stopped and asked who would do that and what they needed to check. We also walked through a rejected application. Some of the answers changed what we had written, and some were things their own team still needed to decide. At least we could put those down as open questions instead of quietly deciding for them while coding.

Unpleasant lesson learned#

I still think they could have explained the request better (also me trying to shift the blame). But when I checked my notes after that first surprise, I was mostly looking for proof that they hadn't mentioned KYC. I wanted something to defend my implementation with, and I found it. That felt reassuring for a while, until we still had to figure out how it will actually be implemented.

Writing the document helped, but we also managed to put a fair amount of guesswork into a much nicer format. I had asked about fields and email confirmation because those answers helped me write the code. I hadn't asked what their business needed to actually run.

It was an inconvenient thing to admit after spending so much energy being annoyed at them.

On the other side of the conversation#

When I later moved into account management, I thought my technical background would make this part easier. I knew what developers needed, or at least I had spent enough time complaining about what clients didn't tell us.

Surely I could come back from a customer meeting with something better than "they want a sign up flow."

Then I would bring a request to the technical team and get a question like "who is supposed to approve this?" I would look through my notes, find a paragraph saying that approval was required, and realize I can't answer their question.

I had asked the customer enough to understand why they wanted the feature, but apparently not enough to explain how they expected it to work. So I got to say "I'll check with them first" to a developer whose frustration I understood a little too well, of course due to past experiences...

Being in those meetings also made me less certain that the customer had a complete specification somewhere and was just refusing to share it. Sometimes one person described the tusk while another described one of the legs. I could follow both explanations during the meeting and still leave with notes that mixed them together. My technical background helped me follow the discussion but I still had to ask what exactly we were actually talking about.

I started trying to repeat the request back with an example before leaving the meeting. If an organization submitted an application, who received it? What would they check before approving it? Walking through that with the customer gave them a chance to correct me while we were still talking. I still missed things, but it was easier to ask there than to come back after confidently explaining the wrong thing to our developers.

Plus it saved us from later embarrassment.

Trying to ask better questions#

These days, I try to ask people to walk me through what they do before I start listing features. For this particular request, I would want to know who was applying, what their team checked, and when the organization could start using the application.

That is, if they said someone had to approve it, I'd ask what happened when that person rejected it. I would probably still need another conversation afterward, but at least it would start with something more useful than another surprise requirement. Also, again, will save me from embarrassment.

I still catch myself thinking about implementation halfway through someone's explanation. Familiar requests are especially tempting, because I can already picture the code and would very much like to get on with writing it. Now I try to stay in the conversation long enough to find out what I've assumed. Sometimes that means asking someone to explain what they mean by sign up, even though I've built it before.

That’s something I’m still working on as I move into solutions architecture. I enjoy getting into the technical details, and I can still get ahead of myself when a request sounds familiar. But I’m trying to ask people to show me what they do before I start proposing changes.

An actual spreadsheet gives me much more to work with than a list of requested features, especially when it contains strange workflows that deletes something in some obscure ERP every Friday evening. I want to know why those are there. There’s a decent chance I’ll eventually be asked to put them into implementation.