Write better requirements or pay for it later

Welcome to No Compromises. A peek into the mind of two old web devs who have seen some things. This is Joel.

And this is Aaron.

So, as a developer familiar with Scrum and Agile, I would obviously love to do stuff that way, but that's not always how it works.

Sometimes you get a bunch more requirements docs, like waterfall. So you end up getting a bunch of requirements, maybe pages, sometimes not.

But you get some sort of formulaic representation of what this next task is, or hopefully you do. Either that or you've written them yourself, or whatever.

Yeah.

And then you can kind of look at that. And I'm used to that, I love that. The more requirements, the better because I know I'm building something out.

And that's really the skill set that we have as developers too. Anything that you can think of, human, I'm going to then make happen for you.

So, I just need to know how you think, because how I think is different, right? I mean, that's what makes humans beautiful too. We all think differently.

So, why that's beautiful is it gives us different ways to solve problems. But where it struggles is any sort of thing you tell me to do,

I'm going to think about doing it differently than you want. And that's where these requirements come in.

Now, that's why we say to people, "Hey, write requirements. The more requirements, the better." I know that's frustrating.

It's like, "Well, just figure it out." Or, "Doesn't everyone think this?" But no, everyone doesn't think that way. So, that's kind of my pitch.

It's like I need requirements because I'm a smart person, you're a smart person, but we think differently.

And so, I need out of your head what you want me to build, and then I will build it.

Yeah, and I'm thinking a lot of the client engagements we have, like there's a business domain that maybe we are not super familiar with.

And so, there's all sorts of, like, baked-in assumptions they have that's blindingly obvious. Like, "Well, everybody knows this."

It's like, I literally don't know what that term means. Like, you keep using this acronym, I don't know what that is.

Right.

So, there's like that knowledge transfer and just removing a whole set of assumptions is like a big part of it. But even more like down at the feature level,

you know, like, "I need a form to add this record." "Okay. Well, what are the required fields? Like, what should it look like? Who's using this?

Does everybody use it the same way?" Like, these are the things that it's so simple to say like, "I want this feature,"

but without going that one extra step, we could build something and it will be that thing, but it might not be the thing they wanted.

So, yeah, I'm with you. More is better. We've also occasionally ignored them, right? Like, "They ask for this, that doesn't make sense.

I'll let them come back a second time and ask for it again." Like, we've done some of these things where, you know, just for reasons of practicality,

we'll push back a little bit. But I'd rather still have the information and then do with it what we will.

Well, what I've noticed is like if someone writes a ton of requirements, I can then do the whole task, start to finish, never stop.

There's no bugs whatsoever, it's completely done. And that's why I love great requirements.

What? No, that's not... Yeah, you're being sarcastic. But, yeah, you do... Yes, even once you have requirements, they're not the final shape of it too.

Because I'm just thinking of a project. I don't know, if we can talk about a little bit here. Where we're integrating with like a pretty

complicated third-party API, and it's like we got extensive requirements, like multiple pages. And I looked at them, and I took a pass at them, right?

Aaron, you're like, "Joel gave me these requirements; they must be good." But once you started working on implementing part of it, it's like,

"This can't be right because this field that you're saying we're supposed to use isn't actually in this payload where we need to use it, and like..."

So, your point is there's still some discovery that's going to happen, but you still need the starting place to get going at least on some level playing field-

Right.

... with the person that's asking for it.

Because it can be really confusing, especially from a business point of view then. When we say something like that, they'll be like,

"Well, if you can't do it right anyway, what's the point of writing the requirements?"

Yeah.

And that's true. Like, that's why we joke about like, "Hey, if we did Agile, which really means business person, you're in a meeting with me

three to four times a week. You're all so involved." And you don't want to do that, but that's how you would do it if that's what you want.

But I want to give a different example. So, imagine I need to travel from Chicago all the way to New York City. I have two different ways to do that, right?

My task is to get there. But regardless, I'm going to get lost in Chicago or in New York City, it doesn't matter. But where do I get lost in general?

Do I get my requirements, my GPS, and take me all the way to New York, and then I have to figure it out? Or do I not even get a GPS and

potentially get lost along the way and end up in Louisiana instead, you know?

Yeah.

And so, yeah, I'm still going to get lost, but I want to get lost in New York, not all the way across the country. And so, that's kind of the

reason why we talk about like even though we're saying these requirements are not right, they're better than nothing.

Yeah, there's definite value in them, but I know we kind of have joked about this too. Because sometimes there's even the request like,

"Well, how long is this going to take? Now that I've given you these requirements, how long is this going to take?" And like, there's still a gray area.

Like, the scenario I gave where we discover this requirement is impossible. Like, so if we estimate it to the best of our ability, it's still going to be wrong.

But I like your point, it's still valuable. Where are you going to get lost? I'm thinking about that analogy now, it's a good one.

Yeah. The sort of another analogy or another way to look at this too is... And this has been a controversial way I've said it in the past,

so this will be great to end the podcast on this. But I've said to people in anger in the past, but now I'm going to say it politely in a more

intelligent way that actually matters. Is, "If I knew all the things you knew, you wouldn't have a job because I can do what I do and I could do what you do.

So, what would be the point of you?"

Right, yeah.

And that's not a threat. I used to use it as a threat when I was an immature developer.

Okay.

But now it's more saying like that's the reason why you need to write these requirements, because you exist and I exist.

Yeah.

If I knew everything, you wouldn't be needed, and that's not the world we live in, right?

Yeah.

And so, you need to write these requirements.

Yeah, that's true. And I appreciate your diplomatic way of stating that here. But before we end, I want to throw one more thing out because we've

experienced this, and I'm sure we're not the only developers that have experienced this. But there's also the danger of maybe a customer using AI

to assist them in writing the requirements. So, I just want to throw that out because it's probably its own whole separate topic. But like,

how do you look at that? Especially if you know or suspect these requirements were generated with Claude or some other tool, some other language model.

Yeah. So, there's two different ways I'll go on that real quick. First of all, if I know the requirements are written by Claude,

I almost don't ever trust them. Because I've not yet seen a business person, and I've not seen most developers read the output

of an AI model from start to finish and understand it.

Okay.

You start reading it and then you start scanning and before you know it, you're at the end and you're like, "Oh, that looks good,"

because the pattern is good. So, first of all I don't really trust them. And I'm probably going to push back and be like, you know...

And it's going to make me irritated because you decided to cut corners, making my job harder.

Yes.

And so, I'm not only irritated but also it costs you more money because your poor requirements generated to save you money actually cost you tokens,

and they gave me the wrong instruction. So, don't do that. But that's not saying I'm against AI. There's a special difference in how I'll phrase this.

AI could be used for helping compile and create the requirements, but not write them. There's a very difference there because it's like a research tool.

So, as you're developing, you might say to your AI, "This is what I wanted to do. What are all the different things I need to consider about that?"

And it will tell you that. You learn from that, and then you write your requirements. Whatever you do, don't be like,

"Great, now write that into the requirements doc." That is not good.

Yeah. Just to push back a little bit? What if somebody used Claude, let's just go with Claude because it's easy to say, to help draft the requirements?

But before they handed them to us, they actually read them all? Or is that just so impossible in your mind that a person would do that?

Reach out to me on Twitter or Bluesky, or whatever, if you've done this.

Okay. Your position is, the person who's going to do that, they're going to feel like they were in the process, they went back and forth,

they scanned it, it's fine. They can't possibly read that whole 10-page document objectively before they hand it off?

No.

It's never been done?

Well, right, and it's the same thing as like even when you write it yourself and you write your stuff, you're going to miss stuff.

But you didn't even write this, so of course you're going to miss stuff. You're going to miss more...

Yeah, you're going to miss more than if you wrote it yourself and reviewed it.

Yeah, that's fair. And I'll say too. Again, going back to this one project I have in mind with the third-party API, I would even use the requirements,

and then I would run those requirements through Claude. I'm like, "Can you cross check this against this like 150-page integration guide from this API?

Does anything stand out that we should know or that doesn't line up?" And it's good at spotting those patterns. But, yeah, I'm with you.

Like, if I know it wrote it, that's very... I almost get combative, and like I want to find an error in the requirements to push it back.

And I'll relate that to our business people, which I kind of talked to a little bit earlier. Is, that was a technical thing, we're reviewing those.

I don't necessarily expect that my business people are going to give me the exact requirements of what XML field or whatever. But it helps

when you think about situations where you have certifications, or you have requirements for federal government or something like that,

and you have a document about that. Write your requirements and then feed it to the AI model and say, "Here is the actual compliance mechanisms

I need to abide by. Does this requirement hit that or not?"

Yeah.

Because those are the things that we won't know. And we'll build something, and then later on you might come back and say, like,

"Hey, it needs to do this because of compliance." And it's like, "Well, I didn't know that. I don't know what you're compliant with."

Yeah. So, it's a useful tool, but I agree with your warning. Is, well taken, because just drafting it and sending it to us is not going to give you the result you want.

I want to be more friendly than I look, Joel.

Okay.

Okay. So, I need some help. So, when I go out walking on the walking trail, I see dogs. And I want to say hi to dogs but my walking pace is reasonably fast.

And I have resting angry face, I wear a black hat and sunglasses.

Okay.

And what I've noticed is that when I walk up to people, I hardly even get a chance to say, "Hello, How's your dog?" or whatever.

So, I'm trying to figure out, is there a sort of mechanism? Should I be taking off my sunglasses every time I see a dog? Should I be slowing down?

How do you even say, "Can I pet your dog?" Like, do I need to talk friendlier? Like, I mean, I don't say, "Could I pet your dog?!"

But I'm like, "Oh, hello, is your dog friendly?" You know, is that normal? People seem to be scared of me.

No. First of all, the dog's not scared of you, right? It's the person that you're thinking might be?

Yeah.

Okay.

Yeah.

I wouldn't take your sunglasses off, especially if it's sunny. Like, if it's at night, maybe. Maybe that would be the time to take them off.

But you mentioned the speed at which you're walking.

Yeah, because I'm out for exercise.

Yeah. So, you could maybe temper the pace, or like just start calling out like in advance. Like, "Hey, I'm going to pet your dog. Incoming on your right."

"How's your dog? Can I say hi?"

Yeah, I've had something like that where I will, maybe if I'm intending to talk to the person, I will slow down a little bit.

And for me too, I usually walk with my AirPods in. I'll even pop one out, it's kind of like a cue, like, "Hey, I'm friendly. I'll talk to you."

Oh. Oh, no, don't get me wrong here, Joel. I don't want to talk to the people, I just want to pet the dog.

We really asked for you to put a lot of effort into writing good requirements because we put a lot of effort, and time, and quality into our work.

If you'd like to benefit from that, then head over to nocompromises.io and see how you can work with Aaron and I.