Hey, what’s going on? Welcome to the Doug Show. I’m Doug Cunnington, and today we’re gonna talk about writing good requirements for software tools that you are trying to build with ai. So I was inspired for this episode because I listened to a couple podcasts and the, the host was talking about actually creating.
A tool that solved a problem that he had. So I’m thinking of the podcast called All the Hacks. Chris Hutchins is the host and he had a spreadsheet, maybe a couple spreadsheets, I’m not a hundred percent sure, but it managed his credit card, reward points and credit card, uh, system. He would know like which card to get next.
And he’s really on top of it. I mean, that’s part of the, the show and one of his great interests. And Chris is very smart. I met him a couple times at, uh, FinCon, super nice guy. We have mutual friends, so we were able to say hello and have a couple drinks and stuff like that. So I would say he’s a light acquaintance.
I think he would recognize me if he saw me. But anyway, Chris used. Some tool. I don’t know if he was using Claude code, I think maybe, but he was using some suite of tools and he talked about creating the tool and spending time planning and he didn’t mention like business and technical and non uh, functional requirements and different things like that.
But he did talk a lot about planning and it made me think about the old days when I had a job and. Essentially I did project management for software implementation. Sometimes they were, you know, huge new brand new things where you, you go to a company and you have to figure out like what you’re building and start from square one.
Other times it’s like new functions. Most of the time it’s like new functions on existing software, new tools or something like that. Anyway, I spent a lot of time doing this and I thought, well, even though I haven’t actually used AI coding tools, I have background knowledge that could make it more useful for people when you’re actually trying to create a tool.
So I’ll break down a couple things and it starts back. I mean, at first I was thinking, ah, you know, my first job I ended up. As a business requirements writer, maybe a technical system, re requirements writer, but essentially when we say requirements, you’re telling the coders and you’re, you’re telling the, the whole project, everyone working on it.
Here’s what the system is supposed to do. Like, here’s what our software that we’re designing is supposed to do. And it could be as simple as. It’s a calculator. I need to be able to do some addition and subtraction and get an answer at the end, like it needs to do that. But also, one of the things that people forget is you need to handle errors.
You need to think about maybe security and other unexpected paths that may pop up. So I mean, if it’s a calculator. You probably don’t want letters in there. You just want numbers because maybe you don’t know what to do with the letters. Maybe it’s a hex calculator where you actually do have letters in there, but you’re not using all, you know, 26 characters in the, you know, English cordy keyboard, right?
You, you want some numbers, few letters. Anyway, the point is. You have to record and write down what you want your system to do, what you want the software to do. And then it gives you something to refer to as you’re building. And the thing is, in the team, maybe the person writing the requirements, maybe that’s the the business person.
So they don’t really know the technical side, they just know they need their software to do certain things and have a certain output. And the coders. Don’t know the business side of it, so they don’t know how it should react. And you maybe have heard of stories where people, uh, like the software folks or the, they’re brilliant software people, and then they build the product, but it looks horrible and it doesn’t work in the same workflow as what a business end user would expect.
So this is how it all comes together. Like I mentioned before, Chris, you know, built a tool and he does have like product management knowledge and he’s a smart dude. He knows how things should work. Very excellent communicator. All that to say he’s spent a lot of time in the planning phase and he was like, really spend time there.
So I’m gonna go through a couple of the ideas here. Now. Those first assignments were me showing up. Kind of like the Bobs on office space and asking people like, oh, how, how do things work around here? What, what do you do? What do you do? What software do you use? How does it work? What is the workflow? And one of my first assignments was like at a, was it Warehouse for a utility company?
So there were, there were parts in there. It was like, okay. You get, you receive parts, how do you inventory them? Where do you put them? Like how does the physical process work? And then how does that interface with the, the software inventory and supply chain management, which, you know, cascades out to other warehouses across the uh, region.
So you end up with something much more complicated. But you know, you’re coming in trying to figure out how things work and if you’re updating the software or you’re. You know, if you need to put new software out there, you’re gonna up upgrade. We’re gonna build some custom solution for you. Then you need to understand how all that stuff works.
So I would show up and ask questions and it was honestly, it’s ridiculous looking back, because I was right outta school. I was like 24 years old, and I’m going in asking people that are in their, you know, mid to senior level of their career. What they do and I don’t know shit about anything. Right. And, and it’s also the utility industry, which I also don’t know anything about.
But I went through like, three weeks of orientation and they sent me out there to ask questions and record it and create documents and then, you know, write system requirements. So. You can, you can do some of the research on your own, ’cause I’m sure there’s a, a certain way to interface with each of the AI assisted coding tools out there.
But generally this would be in the planning phase. So you’re gonna talk. About what your software should do, the problem that it’s solving, how you want the output to be generated. And one of the other big ideas from just software development and something that Chris Hutchins emphasized was working on essentially units of code.
So you would have an encapsulated. A piece of code that did a thing. So it’s a little bit easier to build individual pieces and then put it together. And you could kind of think of this as like a multi-step process. And certain things should happen when you, you know, feed in certain information, your inputs, it’ll be processed, things happen, maybe there’s some follow up questions, and then you get an output.
All that to say most likely whatever you’re working on has multiple phases, so it’s much easier to test and debug if you work on one thing at a time and then put it together at the end, versus building a huge, massive piece of software and then trying to debug when you’re. You don’t know where the issue is because the thing is things will go wrong.
It will be incorrect first. Right? There’s always bugs. There’s always some issue with the system overall. So in those early days it was, it was interesting writing those software requirements and you probably, I’m assuming, can find templates out there where you could say. Have, uh, all, all the sort of security requirements that you need, maybe different, uh, business requirements specifically for the problem that you’re trying to solve.
So in Chris’s case, he actually built the, the credit card and point management tool. So he needed to interface with different systems out there, your credit card. So he would, he found, uh, an interface, I think called plaid that you’re able to integrate with banking. Systems out there so that people could get like their balance and just what’s going on on their card.
Essentially the dashboard of their credit card, including the points so you could, you know, put in your information and have the tool running and essentially it’s going out, grabbing real time information from your credit card tools. So most likely it’s better to. Write the individual call for each system, so you’re like, okay, I’m able to contact Chase.
I’m able to contact Bank of America, or fill in the blank. So you can test each one of those. I don’t know how plaid works, but all, all that to say, it’s much better to work on things like one little piece at a time and work on it incrementally. Maybe that’s obvious, but I, I know some people that are not from the software industry.
You wouldn’t know that. You would think, oh, right, I’m gonna build this tool that does all this stuff and I’m gonna build it all together right now and it should mostly work. ’cause I heard these AI coding tools are really good and I could just hit go after putting in the requirements and it should work.
And the chances are there’s gonna be a couple mistakes in there. A quick tangent on this because the other inspiration for this episode was a couple articles that I read on X, which if you’re out there listening to this, you, you probably know this already, but I wasn’t really paying attention. I don’t spend any time on X or.
Any social media that sort of, uh, you know, I, I guess X isn’t necessarily business related, but there were a couple articles that went viral and they showed up on my radar because they were mentioned in podcasts that I like, and then in newsletters. And finally when one of them was referenced like three times, I was like, okay, fine.
I will go check out this article. And there was another AI. Related article on X that went viral also. So two of them came out in the last few weeks. You probably read them and I think, you know, if you see the article in the number of times it was read, it’s in the millions. It’s in the like tens of millions.
So it was definitely referenced the big takeaway from both of the articles and maybe blending ’em a little together here, but. The, the main idea is like AI is going crazy and it’s much better than you think. There’s actually not much evidence in the article. It was just very emotional, and I’m skeptical most of the time, and I’m actually skeptical of the articles.
What they did say is, yeah, I just went into one of these tools and I used to have to spend weeks debugging and figuring things out. Now. I could just go in, I could put in the requirements. They don’t say requirements. They’ve said I could just describe the product, the software in plain English, and then I hit, uh, whatever, compile, go build the tool, whatever.
I come back in four hours and it works. They just said, yep, and it works. I’m a little skeptical on that. I think. If the inputs are really good, maybe that could work. Or maybe if it’s a standardized kind of tool that’s out there, maybe an almost off the shelf kind of thing where it’s not necessarily a commodity, but like it’s something that has been done.
There’s already a tool out there that does a similar thing. Maybe that could happen, but I am skeptical of just someone. Being able to describe a tool in plain English and then getting that actual tool at the end of the output from the AI tool. If you have done that, let me know. Feedback at Doug show.
Super interested, or if you’ve had little projects that you’re working on. So the tangent is I have been seeing a couple of these articles going viral. On X articles, which is essentially, it’s a blog post. I mean, it’s just a blog post on there. So there’s a blog and then people could share it around.
There’s some viral component to it. So I listened to Cal Newport’s podcast and he mentioned like, oh yeah, I bet there’s gonna be a ton of videos out there on how to go viral on X, which while I don’t know how to do it. It could be interesting to analyze a couple of the articles that have gone viral and I don’t think there’s very many of them out there.
These videos out there on how to go viral on X, especially that are recent. So Cal speculated that it will get crowded very quickly and probably. It’ll just be like a couple months when people are able to like go viral. That said, I think the articles that I read, they were both sort of AI related for sure, but also sensational and making huge claims that were, I mean, it seemed hyperbolic for sure, but we’ll see.
We’ll see. Okay. A couple things, and I did a tiny bit of research using a Gemini, just like, Hey, like what’s, what’s your take on requirements for AI assisted coding? A couple things that they referenced, which I don’t remember from my days, but maybe this is the right way to think about it, especially if you are using one of the tools.
And like I said, I, I gave the caveat so many times, I haven’t used the tools, but I’m pretty sure this information would be helpful. So the research that I did. It mentioned to let the system, we’ll just call the ai, um, we’ll just call it an AI tool, right? Describe the context. So that’s around like why you’re trying to, to do the tool, why you’re trying to create the tool, what problem you’re trying to solve.
Next is action, and that is what the AI should do, what you expect AI to do with this information, the result. That’s the definition of being done, probably what output you should have. And the next is evaluation, which I, this one didn’t make sense to me, but it did describe like non-functional requirements such as being mobile responsive, that sort of thing.
It pro like Gemini provided this sort of framework and I think if you refer to whatever AI coding. Assistant you are working with? Probably in the, you know, the planning phase in the documentation, it will probably tell you like the best way to write requirements. And I think you could probably, to keep it simple, you could divide it up in a couple areas where, number one, it’s like what you want the software to do, inputs it might receive and the outputs that you expect.
The other area, which is sort of not related to. The core functionality. These are like non-functional requirements. This is error handling, so the unexpected inputs, as I mentioned before, if you have a a calculator, you probably don’t want letters in there, and you could think about it in that way where there’s all these unexpected paths.
What happens if the system gets overloaded by too many people connecting? Like what? How do you handle that as well? The others around security. The other is performance. So you know if you know how many users are gonna use the tool, if there’s only gonna be one, or like how much data should it be able to handle?
So there’s a bunch of ideas around what you need to do to handle performance. The last one is around testing, and that’s a whole other area. One of the other big places that I spent time was in testing, and there’s, you know, there’s unit testing like I mentioned before, where you have, uh, sort of an encapsulated piece of software that does something and it will feed that output to something else, and your overall software is put together of these different units.
The terminology might be a little different nowadays. It’s been a long time since I’ve done this stuff, folks, but when you’re looking at. The unit testing, you may have like some core things that test the functionality and what typically happens is you have a mapping from your requirement. Your calculator should accept numbers, for example, and then you have a test where you input numbers and you make sure the calculator can accept that sort of a negative test to take care of the error handling area.
Related to that same idea is. The system should not accept letters because it’s a calculator, so it shouldn’t accept letters. So the test for that would be inputting letters and it would be, you know, rejected or it wouldn’t accept that input for however you want it to work. The point is, you have a way.
To test the success path and the non successs path, and a way to handle that non successs path in a graceful way, right? You don’t want the computer to shut down when there’s poor input, right? You want it to do something graceful so that the. Person can keep using the tool, hopefully solving their problem with testing.
There’s also many different layers, and this is one of the things that I’ve harped on before, is like when lay people create software tools and they don’t have a technical co-founder, a technical person to provide some oversight, when someone’s like, Hey Doug, I created a new tool. Do you wanna check it out?
The answer is no. I, I really don’t want to test it out because I think there’s gonna be a lot of bugs. So come back to me when version three is out. When there’s thousands of users or so, something like that. Like I’m like, I’m not gonna do your testing for you. Chances are like, people didn’t test it thoroughly because they didn’t go through this testing phase where you think about like test planning phase where you think about.
What your software should do when certain things happen, especially things that you don’t expect. ’cause that’s where you get screwed up. If you have a normal path where people are just entering numbers, they’re doing simple addition, no problem, you know how to handle that. But when you have, you know, whatever random data coming in, things can get squirrely.
And when people don’t test their software properly, then you end up with an issue. So you have like your unit testing, then you have the system testing where you’re like, okay, each unit worked how I expected, let’s put the whole thing together and see what happens. And then you have testing a test plan for that so that you could test, you know, the full system all put together.
You would think things are gonna work, but a lot of times when you put everything together. More unexpected things happen, so you do have to troubleshoot that. This is an area that I actually excelled in with my short software engineering career. I was pretty good at debugging and I knew that obviously you’re not gonna get it right the first time around, but I was really good at debugging and.
Uh, using, incremental, unit testing to understand like where the mistake was and then how to fix it. So I got pretty good at that. Sort of just, I mean, it takes forever to do this sort of testing, or at least it did back in the day. Maybe with AI tools, you could test much faster. Next area, this is the big one.
It’s regression testing, so something’s gonna go wrong. Let’s say I find something wrong in unit testing, or actually, let’s say it’s system testing. So each unit is working fine. It puts it together, the system works. Okay. And then I find some bug with, maybe it’s not a, like a error handling situation, but it’s just an unexpected result.
For some reason there’s some bug in there. I don’t, I don’t know what’s causing it. I do some debugging. I figure it out. I identify the unit, I fix the problem, and then I test it again and it works great. So the thing is, when you fix one thing, you might have broken something else along the way. Even if it seems unrelated, you may have done that.
And under the hood, if you’re using the AI coding. Assistant, then you don’t know what’s going on under the hood. So when you fix a problem, you maybe could have broken something else. So regression testing is like a set of tests that you go back and retest every single time. Whenever there’s new code, whenever there’s a change, you go back and you.
Test things that should not be broken, that are related to core functionality. These could be pretty thorough. I mean, the, the thing is, it’s one of those areas where I remember late nights we’re supposed to deploy, code testing is behind for some reason, and someone’s like, can we, we need to push the code this weekend because of the maintenance window.
However, we don’t have time to do regression testing. They’re, they’re always like, uh, can we skip, can we skip some testing here? So they’re like, oh, can we skip the regression testing? And it’s like, I, we need to do the regression testing. Like when you, when you ship the code, you don’t want to break the core functionality of what you’re trying to do.
So that is one of the big ones. I’m gonna keep it brief and quickly summarize, study up on requirements and planning for software. I think you could probably read a couple articles. One of the things that AI is very good at is coaching through things like this where there’s a huge amount of documentation across, you know, so many different, uh, specific software, um, sort of strategies and, and planning and, you know, project management, product management.
There’s a solid chance if you go to your favorite AI tool and you ask about writing good requirements. For AI assisted coding, then you should be in really good shape. I suspect the AI tools that you are using will probably guide you on how they like to have the planning done. I think if you could tie this together with the actual testing and planning on testing and maybe, you know, asking the tool that you’re using.
How much can we do on the test planning? I wanna make sure this software process works really well and I understand about, you know, regression testing and I wanna make sure that if we, if we fix something, we don’t break anything else. Again, AI tools are your friends in this case. Last thing I. Have been using a notebook again.
So I made the notes for this specific episode in this like big giant notebook. It’s a probably, it’s like a nine by 11, kind of a jumbo sized notebook. And I was using it specifically for my now canceled podcast called Ranking Revolution. And it was a couple years ago I had an idea to start a podcast.
Get some advertisers, get it rolling and then sell it. I launched it, I think it was 2023. It’s been a few years. Maybe it was 2024. It could have been 2024. Yes. The dates in this notebook are 2024. So I started it ’cause I really like podcasting and I was like, Hey, I’m gonna launch a podcast and I’m gonna try to sell it later.
And around this time, I mean, SEO was changing already, but the focus was SEO and marketing. Basically the show didn’t get traction. I published maybe like 40 to 45 episodes and it was fine, but it never really took off. 45 episodes is a, a decent number to give it a try. I was hoping that I was gonna be able to sell it to like a, a marketing company or a software company or a marketing agency, a.
Probably, you know, SEO related, but even though things were shifting in 2024, I was like, ah, this should still work. I mean, there were conferences and there are still conferences around SEO, but they are shifting a little bit. After working on it for maybe, I can’t remember, say five months. I was like, you know what?
This is not going anywhere. It doesn’t feel like it’s working and I’m not really enjoying it that much. So I quit anyway and I was like, I’ve only used like a a third of this notebook or so, which was more than I expected by the way, but it’s a great notebook. So I went back to it and a lot of times I’m sort of a single use notebook person, so I had like a notebook when I was logging my workouts, which I should probably go back to like keeping track of your workouts is really important.
This one I was using just for podcasting stuff and. I haven’t touched it in a very long time. It, it may be like, oh, almost two years since I’ve written anything in here. But I do use these small little field notebooks and it, these are more general purpose, so I don’t currently, I don’t have any of ’em that are just like one use, but I think I might do it.
I love this size because I can’t actually keep it in my pocket. For the listeners out there, I guess they’re about. Three by five or so, if I had to guess. But it’s like the standard field notes. Moleskin has a similar size and it’s soft cover, so they’re thin. I think there’s 48 pages. They come, like with plain paper like this one.
Um, I do put like pictures and stuff in these occasionally just to, to mix it up. And I, I did it in the big notebook too. But these field notebooks, it’ll be, uh, some of ’em are blank. They have grid and they have lines. So you could pick whichever you want. And they have, you know, different logos on the outsider.
Art on the outside. So this one’s more like abstract and it’s like glossy. This other one there’s a whole national Park series, so I have a few of these as well. This one’s Yellowstone, so there’s bison and then, uh, old Faithful in here. And this one is a matte cover. If they’re pretty durable, they’re not, you know, bulletproof or anything like that, but I can carry ’em around in my pocket.
And I have been trying to just write and journal a little bit more, keep track of stuff. And one thing I should do is go through. Each of the notebooks a little more often. I’m not too strict about it, but probably the best way is like once a week kind of go through it, see if I had any meaningful notes that I should transfer to a larger notebook.
But I, I will be experimenting a little bit with. Probably having like the single use notebook kind of idea. And this big one was great for writing any podcast ideas. There’s plenty of room. I put some pictures in here too, and I’m, I’m curious if any folks are big journalists out there, or, or like these little notebooks.
But I do appreciate ’em and I like the aesthetic overall, especially like the, the National Park ones. But field notes are, they’re pretty good, I gotta say. They’re. They’re overpriced, but it’s not like I’m blowing through ’em. So I think each of the little notebooks is probably like five bucks each. And if you went to fuck, you could probably go to the dollar store and get something that’s almost the same as far as the size and and weight and stuff like that.
These are probably a little more durable, but it’s a good company. And again, I like the aesthetic and I’m not blowing through ’em. So. It’s worth checking out. Anyway, if you have any ideas, if you have thoughts on this episode, the ideas around requirements for software using AI tools, especially if you have created an actual tool that you’re using on a regular basis where you solved a problem for yourself.
That’s interesting. Even more interesting is if you actually created something and then you. Have customers that are actually using the tool out there, even on a beta level. But super interested in hearing like how good these AI tools are. And I know what you’re thinking, Doug, why don’t you just give it a shot?
I don’t have a specific problem that I’m trying to solve currently, so when one comes up, I’m sure I’ll be like, oh, I’ll see if I can, I can get this problem solved and code it out myself. But I haven’t had one pop up recently. Feedback at Doug show. We’ll catch on the next episode.