Welcome to Bytes in Balance, the podcast where we navigate the wild world of software engineering together. I'm Dan and this is Damian. We have been juggling code, teams and sanity for over 35 years combined. From junior devs to principal engineers, we have worn every hat in the industry. In this podcast, we're sharing our journey, lessons learned and mentoring tricks to help you find your own balance.
It's not just about the tech. We dive into people, psychology, communication, and all the messy bits in between. Think of it as group therapy for the digital age. We bend to swap word stories and share what we think is solid advice. Sometimes we even bring guests to shake things up. This podcast is our way of tackling the stress, burnout, and growth pains that come with the job. It's as much a balancing act for us as it is for you. Grab a seat and let's navigate this madness together.
You'll find some interesting links in the episode description if you want to learn more about us or the topics we discuss. All right, let's get started. Hey, Dan. Good to see you again. Yeah. Nice to be here. So what are we talking today? Yeah. So last episode, you know, we talked about what is engineering culture and we talked about how do you change the engineering culture? And a lot of that was pretty high level and abstract.
We thought it would be good to zoom in and focus on one aspect of engineering culture, which is your software design process. That can be a lot of different things, but I think we wanted to do a whole episode on diving into what is a software design process? Why do you do it? What are the goals? How should you be looking at this at different levels? How do you improve it?
Yeah, basically just talking about all those different aspects of the engineering culture, which is how do you plan out what you're going to build? Yeah, I think this is a very interesting topic because a lot of things in the software actually start with design and a lot of the success.
or failure could be related to design, among other things, right? Don't get me wrong. This is not the only variable. But I think it's a very, very interesting topic. And we have seen a lot in that sense. Yeah. So why don't we try to scope this discussion? What is a design process? What exactly are we talking about?
talking about, just so we don't overuse that phrase, let's get kind of concrete. And then what's the impact? Like, why do you do it? What's the point? For me is the process in which we take some type of requirement. from business from a product manager etc and we visualize you know and even document
How are we going to transform those requirements into working software? And to me, I don't think design is something that you do only once. I think design is something that probably you put a lot of effort in certain. phases and moments of the project, but you probably are constantly thinking on design and design is something that evolves in time.
Finally, your goal is to basically take these requirements and put together something, visualize, have the vision of something that actually can successfully fulfill those requirements.
Right. And when you say something, I mean, you're talking about some kind of artifact, a document, a diagram, something scribbled on a napkin, you know, it could be simple, it could be complex, but what's the value in kind of capturing this and writing it down? Why don't you just do this design process in your head before you sit down? coding and then you go start coding. What's the purpose of all the process? I think it's managing complexity, mitigating risk.
aligning people, getting different opinions, trying to get other people to give us feedback, to know what we don't know. I think there are a bunch of things. I made a small list, you know, that I can talk a bit about. Socialized design, for example, is like share what you're... thinking with others, capture decisions. It's like we make a lot of decisions and then we are six months later thinking like, okay, why did we make this decision or why is this software working this way?
So I think there is a lot of, let's say, advantages in doing a proper design process that can help us with these things. And you know, sometimes a proper design process is capturing something in a napkin and going with it. I'm not talking about very complex long documents and stuff like that, or very complex cumbersome waterfall processes and stuff like that. It's like when you do agile, you do some type of design.
Also, agile doesn't mean there is no design. Would you say that design is an individual effort or an individual process, or it's more like a collective process, you know, something you do in a group? I would say there is fundamental aspects of it that are individual and fundamental aspects of it that are collective. In my experience, I have participated in the science in which I, as an individual, sit down, put something together, think through it.
run my creativity through it, get to certain conclusions and so on and so forth. But that only takes me so far. and there is a point in which you need to share this with a group and then it starts being a collective thing and you get feedback and you get new ideas and somebody had a brilliant idea of how to do this differently and then you incorporate those things and then at that stage you can think of this as a collective
proactive process. And then you take all those things and then you go back to the individual aspect of it and then you keep working on it and repeat. I think there is value on looking at these things in both ways. Yeah, definitely. As you were talking, I was thinking about this too. You know, it kind of depends on what...
phase of a project you're in. When I think about specific projects that I've worked on where I'm writing some kind of a design document or sketching a diagram or whatever, I have specific goals in mind depending on where I am. If it's early on in the project, I might be engaging.
a senior engineer or a principal engineer very casually just going to their office and just, Hey, can we chat about this? I have some ideas, but I'm not really sure. Can you help point me in the right direction? And in that phase, I don't have much concrete yet. I haven't made a lot of decisions yet. I'm just looking for early.
guidance. And then later on, maybe a month down the road, I have made a lot of decisions. I've gathered a lot of requirements. I've put all this together into a design doc. And now I'm sharing it with a bunch of people. I have an initial direction already. I have some ideas of where I'm going. And what I'm looking for now is for people to go make sure that I've crossed my T's and dotted my I's, double checking, looking for gaps in my thinking or big holes in my thinking or whatever.
In each place, in each point, I have a specific idea in mind of what my goals are. I'm looking for feedback on this. I'm looking for initial direction. Maybe I'm not even looking for that much feedback. Maybe I'm just circulating the ideas and sharing it so that everybody knows what we're doing and we're on the same page. I agree with you.
I think there is this aspect of when you are working alone, you can go faster in certain things. Of course, you are more prone to make certain mistakes and you don't have the advantage of having a group behind you or having different opinions and perspectives. But you can go faster in creating and ideating and documenting and putting together certain things.
When you enter to work into a group, you are going to go way slower. And sometimes, you know, designing by committee could not be a good idea because you get paralyzed. If you're trying to design in a big group, sometimes nobody actually really owns.
decisions. Nobody really owns the design. Everybody wants to go in a different direction. Everybody has a different input or has a different opinion or wants some type of visibility in the whole thing. So it's very hard to actually make progress sometimes in those aspects. So I think
And we're going to go there probably in the pitfalls later. It's like the signing by committee is not necessarily the best idea. That specific situation, taking a project that up until now has been the brainchild of one person, and then now incorporate bringing a bunch of people on. That's actually a really interesting situation where you almost have a design review. And the goal is not necessarily to gather a bunch of feedback, but it's just to bring a bunch of people up to speed.
If you don't do this, basically the first few months of this project, everybody's asking the same questions to this one person. Hey, why did you do it this way? Why didn't we do this? And they're basically answering the same thing over and over again. And then writing all this stuff down and saying, here's where we're at. Here's the decisions I've made.
So far, they may not be perfect, but here's what I've made and here's the consequences of them. That's a great way to bring a bunch of people into a group, as long as you have the right goals. You're not looking for everybody to go debate the color of the bike shed, you know, over and over and over. What I have found is that...
You have to take input, you have to listen, you have to incorporate sometimes those things and sometimes you have to just make your own mind and go ahead with some approach. That's okay, because otherwise you cannot make everybody happy and take all the inputs in consideration. Sometimes there are contradictory things here. And that's when paralysis starts creeping in sometimes, right?
So I've been in situations in which it's like you have somebody that has a great idea. You think it's a great idea, but you realize that's going to take three times what this other approach is going to take. And business is probably not willing to take that extra time. And you need to say, here we are making the...
compromise of not going with this approach, going with this because it's going to be cheaper in this sense and so on and so forth. And I think that work compromise and the work trade-off, together with words like risks and so on and so forth, are really important words to think in terms of design and as part of the process of design and the goals, because you are making compromises and you are taking trade-offs.
as well as you are assessing risks. I'm deciding to have two options that are equally good or more or less equally good, but I'm deciding for one and I'm making these trade-offs. I'm willing to take a hit in operations.
because I really want to have this ready by this time. Actually, you're calling out a really important point. This is a really important role of a senior engineer, a staff engineer, somebody more senior in the process. I've seen this exact situation happen many times. You're in a design discussion.
or a design review or something, you kind of realize that everybody in the room has this implicit assumption that the goal of the meeting is to make everybody happy and solve every possible problem and mitigate every possible risk and do it so that absolutely there will be no... throughout the implementation, you will have checked everything, everything.
And if you didn't, if some surprise happens later on down the road, then that's a failure of the design process. This is what people implicitly assume sometimes. It's totally not true. This kind of thinking will lead you to way over design and over invest in your design phase. And it won't help you. You'll still have surprises. and mistakes and things you forgot later on.
but i think a really important value really important role of the senior engineer is to sit there and kind of bring everybody to the same goals and using those words those magic words of trade-off and compromise and even just who owns this decision sometimes that was the magic phrase where you're in a room and there's a couple of differing opinions. And I'll just say, okay, well, Joe here owns the decision because this is his team and his service and his project.
We've heard input from a couple of different people and stuff like that, but just calling out like, okay, the ultimate decision rests with this person, or this is how we're going to make the ultimate decision. It's going to be based on this.
you know, can help bring the group to recognize those trade-offs and to have more of a mindset of, oh yeah, we're optimizing for a bunch of different trade-offs, one of which is the cost of this process of all of us sitting in the room. Let's make sure to keep that in mind as we find out.
a mutually beneficial solution? I think design is a continuous process. I have been in situations, and probably you have been in situations too, in which, okay, you did the design, you make some decisions, you're in the middle of the project, six months, one year project, and so on and so forth, and something changed.
Or do you realize that some technology doesn't behave exactly the way you expected? Or do you realize that there is some security issue that you were not thinking about? Unfortunately, it happens, right? And then you just have to change the signs. are already in the middle of the process. As you already mentioned, you can design to make sure that every detail goes as expected and is perfect. There is only some level that is good enough, and you have to move on.
How do you think people should be looking at the design process if they're a junior engineer versus a mid-level versus a senior or a staff or principal, whatever their company calls it? When you're at different stages in your career, different levels of seniority, how do you think people should be looking at the process?
I think if you are a junior, you are basically learning. Hopefully you are in an organization in which you are being included in these conversations, or you can ask to be included for sure. And you are like a sponge getting and learning from the conversations as much as you can. And you are learning about architecture. You're learning about decisions that are being made and why. And you're learning about technologies. And you're learning about this.
all process of discussion and you're learning about trade-offs and all these kind of things. And you're learning about risks, which is very important. It's like maybe complementing what we just talked about. You will not over design for sure. You don't have to over design. important. An important goal of design is to identify risks.
Because when you do see a risk, then maybe at that point you do have to dive deep there and do some extra work. So hopefully if you're a junior engineer, you are in all this process. And you are trying to remember, you know, the higher you get in your levels in your career, the more scope. you're going to manage
So if you're a junior engineer, somebody's going to ask you to make a very small design of a very small feature, you know, and you should be trying to apply these things that you're learning through this process. And same when you are a mid-level engineer, you are going to be tackling bigger designs in that sense, and you should probably be learning.
figuring it out how you are going to communicate these designs and how you are going to drive these discussions and so on and so forth and what things you should be focusing on and you're also probably learning there and i guess when you're senior or principal your scope goes up
And at that point, you're going to start also facilitating this type of conversations where you are not the owner necessarily of the design, but you actually are trying to facilitate these conversations, are trying to figure it out. Is this design good enough for what we need to implement?
Right. At that point, the process is your avenue for influencing the org. You're thinking about the process as a whole and trying to engineer the process as opposed to engineer the specific designs that you're working on. yeah i think if you're a principal engineer it's not that you are not going to design anything ever again it's like you are for sure you probably are going to take a interesting tricky long-term problem and tackle it but your influence let's say or your value
is probably more about influencing others and making sure the organization is aligned and making sure that critical designs get enough attention. Just start playing this game of basically distributing your time across all these things, influencing the organization.
in that sense through this type of process. Yeah. And when you do spend time on design, which yeah, hopefully still happens when you're a senior and a principal, you're producing designs that maybe will serve as examples for others. You're thinking about that as well. Yeah, that makes sense.
Okay, Dan, I think we have covered the most important things of what is a design process and what is the impact that it could have in the organization? What are the goals? And we have talked a little bit of how different levels of software developer engineers should be looking at this.
What do you think about talking about some of the pitfalls and mistakes that we have seen in the design process? Yeah, absolutely. I think that's really important. We also need to jump to some positive examples and some best practices and ideas, but there are so many ways to do this. wrong. So let's name a few.
And I think these are two sides of the same coin, talking about some pitfalls or mistakes. We're probably going to end repeating some of this again when we talk about some best practices, so it makes sense. Yeah, well, just to name a few, I mean, an easy one is basically you have... discussion. You talk as a team or maybe you do this individually and then you just don't write anything down. You don't capture anything.
And it's easy to fall into this because of course it's easier and it's less work and teams can get by. If you're still discussing as a team, you're getting half of the value out of this. You're having the discussions, but over time, if you don't write anything down, you don't document this. It's really hard to know when things change. When do you need to change your approach?
It's incredibly valuable. The longer you spend in your career, you realize the amount of times that you've gone back to do some sort of archaeology expedition, looking back in some old documents to understand why something was done a particular way. And that's really valuable. You're always sitting there cursing the pre-
previous maintainers, maybe those were you who didn't write things down because you're now you're like, wow, I really wish I knew the purpose of this code. I wish I knew the purpose of this decision. Does this make sense anymore? Maybe it doesn't. But yeah, I would say the biggest pitfall is just not capturing things, not writing something down. and not saving it for later.
Yeah, I've been there, done that, suffered it, learned the lesson. I used to say to people, like, why do we write things? Because in six months, we are going to be wondering what happened here? Why did we decide to do this? Or even, you know, in two...
three years we're going to try to understand how did this system work that we don't remember because we haven't changed it in like two three years it's a fundamental thing and you don't have to write a lot that's actually the other side of the coin that we should talk about next is over complicating the process but really you don't
need a lot. You just need to capture the problem statement, put a date on it, put the problem statement, put the constraints that you were under at the time, the goals that you were facing at the time, what you decided to do, what alternatives you considered but you didn't do. And that's it.
So yeah, that's one side of the coin. Let's talk about the other side of the coin, though, which is overcomplicating the process. I think this is also something that both of us have seen a lot. This can lead to a lot of different problems. I mean, I think people are sometimes tempted to overinvest in this process for a lot of reasons.
At big companies, a lot of times the promotion and career advancement process is tied to big projects you have led and you have delivered. And sometimes people tend to overcomplicate their designs because they think that that's what they need to do to get promoted. People have heard about promotion.
driven development. And there's other terms like that. This is for sure a problem. It's hard to call people out. But the impact is design discussions that don't see a lot of engagement. Everybody's reading these massive documents that takes half the time just to get through the document. If the doc
is too complex, a lot of times people won't have as much input. They won't say vocalize some things that they're thinking because they're afraid that it's too big of a change. They're not going to take the advice anyways. Yeah, totally. I mean, a 400-page document or the signed document is not a signed document, it's a spec, right? In a one-hour meeting, if somebody's coming to you with a 400-page document, it's very hard to approach to that. And if you are...
probably dealing with other things is that people just don't read those documents. That's part of the problem. Yeah, one pitfall is to have overly complex designs and overly complex documents themselves, because instead of helping the discussion, sometimes they actually stop the discussion. It's hard for us to give advice as to what the right level of complexity is for the problem. But I would say...
think about the goals. Okay, if you're writing some document, think about how it's going to be used. Is it just to document what you did so that future versions of you can go look back? Then sure, you can add lots of details. But if the goal is to facilitate a discussion and a discussion where you might receive input and you might change your mind, don't overinvest in your initial design because that's going to lead you to be less flexible. That's going to lead you mentally to...
dig your heels in and think, well, I spent four hours building this hugely complex diagram in draw.io. And even though you're giving me some good ideas of how to simplify it, now I'm mentally anchored to this huge spaghetti ball of shit that I want to go implement.
if you're early on in the design process you should not have a super complex diagram you should not have a super complex design document because you're hoping to get to gather feedback and input you might change your direction pretty significantly you want to leave yourself open to that if you are later on in the process and you just need to get a whole bunch
of senior people to double check all of your assumptions and dot your I's and cross your T's, your document can be more complex. It's okay. I guess the best advice I can give is to think carefully about your goals and make sure your document is geared towards those goals. I think it's trying to figure it out. What are the decisions that actually is worth capturing? To give you an example, if I have 60 use cases, 60 user stories, most likely...
you are going to create a design or a thought process for the most significant three, four, five. And the remaining 55 are probably going to fit in any of these two categories. So you don't want to actually have a spec. or an individual piece of the sign or section of the document for each of these 60 use cases.
I just want to look at them and say like, okay, yes, this one I can fit here. And overall, my architecture that actually can accommodate these use cases reasonably at scale or whatever other concerns you have in that sense is going to be this. That's a simpler problem to tackle. That's probably a document that you can put together in six, seven pages or something like that and have a front discussion. Or maybe from those 60 use cases, there is one that looks really tricky.
scaling security or so on and so forth perspective. And maybe that's an additional document, four or five pages document that you can follow up and dive deep on how are you going to address those risks. And that's why thinking in terms of trade-offs. risks, etc. It's important because it's the type of things that allows you to prioritize and allows you to drive these things properly and focus your attention in the right things without entering a bunch of text that doesn't make sense.
I think people sometimes end writing these huge and long documents because there is this satisfaction. It's like, I'm producing volume of things. And then you have this false sense that you're making progress when you maybe are procrastinating actually a very important...
important risks that you're not facing. You're just writing these normal use cases that all fit more or less in the same category and you're missing out the important things. The way I approach to this is like, what is the stuff that actually I'm afraid of? And this is on this system where it's a sign.
And that's what I'm going to tackle first. And once I have that, probably some of the other use cases or whatever, it's like, OK, this is easy. This is business as usual. This is normal API, whatever. So I don't have to document that much.
This is again, the value of having a senior engineer, a principal engineer available to you in this process. Cause what I always would tell people is, Hey, if you're writing a design, come engage me early, come talk to me right away. Let's brainstorm. Like I would actually ask those questions.
What are you scared of? What is worrying you? Because I'm not a psychic. I don't know what's going to happen with this project. But usually the person who's doing the design, they know what the risks are. And so I would just ask that exact question.
I'm glad you brought that up. What are you scared of? What are the risks? Okay, write those down and address them. And let's meet next week and let's talk about it. And I think it's selfish also, self-interest from our side, because we really don't want to deal with the problem as principals engineer downstream two, three. weeks or six months. The earlier we take it, the better.
It's selfishness in like the Larry Wall. You know what I'm talking about? No, not really. Oh, Larry Wall is the inventor of Perl. He wrote about the virtues of software engineers and it's like laziness.
hubris you want to be so proud of your code such an egotist about your code that you write it and it easy to understand or very clean and maintainable i don't remember all the details But yeah, be selfish as a principal engineer, make sure that nobody's gonna wake you up at 2am in six months, because you're the thing has a bad architecture.
And by the way, I think we all have gone through these pitfalls. I have been in that situation of procrastinating something and writing a bunch of other stuff just because it feels good. I'm making progress. Bye.
I heard a couple of weeks ago, I don't remember the exact context, somebody was talking about startups and software teams and they were saying like, okay, if you have to build this complex pedestal with a very complex machinery on top of it, and then people just start building the pedestal first. Like, no.
Build the complex machine first, which is the first point that can fail, that can go wrong, it can get raised. The pedestal, we know how to build pedestals, right? Well, yeah, you fall victim to that at any point in the process, not just the design. It's very tempting to focus on the part that you know is achievable and you know is doable, as opposed to...
to the scary part that you're not sure is possible. So we have talked about some of the pitfalls or mistakes. What about some best practices, some tricks or interesting approaches that you have found? I can think of a whole bunch of them, but if we're thinking about the design reviews, the meetings, the discussions where you're meeting as a team, maybe you're reviewing a document or whatever.
most basic tips is just to make sure that you have engagement. Make sure that people are participating, make sure that people feel like their voices are heard, and make sure that people are giving real actionable feedback. It's easy to get into these patterns where your design reviews are essentially rubber stamping. Nobody has any real significant feedback.
Over time, that's going to leave people not seeing value in the process. They don't want to produce a big document just to have people go, yep, looks fine. If you're the senior engineer, if you're the principal engineer in charge of this team, it's on you to encourage this and to make sure. You may have to do this at first, but your goal is to get other people engaged and have other people raise their hands and give good, constructive, useful, well-timed feedback.
Yeah, I think even from the learning perspective, if you are in such meetings and there are things that you don't understand, just ask the questions.
I don't think there are dumb questions, by the way, in those situations. Just ask the questions and, you know, you're learning something from the design and maybe your question is actually relevant. I have been in meetings in which somebody asks what seems to be an innocent question and basically that... derails, moves the direction of the design completely in another direction.
An old mentor that I had, a principal engineer that was my mentor, he basically said that also you can mischievously use this. He would influence these meetings and these designs basically by asking questions. And I adopted his tactic during this design. like, hey, what happens if this happens? Or what happens if this breaks? Sometimes you know the answer, but you're asking the unison question and see what happens.
Yeah. And you know what I have seen too, on a team that I was on a long time ago, if you keep doing that over and over and over asking those same kinds of questions, eventually people will start doing that even when you're not there. I was on a team where we were in a design review and someone spoke up and they said, ah, this guy, our
Principal engineer is not here. But if he were, he would have asked this question. And I was like, man, that's how you know that guy was good at his job. Mission accomplished. Yes, exactly. He's not even there. And people are imagining what this person would say. and asking the right questions. Ultimately the right outcome happened right there.
And sometimes if you're facilitating these meetings, just push people to talk a bit. It's healthy, actually. Go around the table and try to ask those questions. You see that what is happening is cruel stamping. Hey, I see that you've been pretty quiet during this meeting. What do you think? You think this is going to work? work? You skeptical? Yeah, exactly. Sometimes people need to push.
There is no dumb questions. Remember something. Part of the goal of these design meetings is not only to gather feedback or opinions or so on and so forth. It's also socialize the design. And it's also help other engineers to grow. make that growth process effective, it's important to participate in that growth process and ask the questions and learn from the, be curious, learn from the design. Hey, so I'm curious to get even more concrete. Let's imagine that one of our four listeners is driving
to work right now and they have to write a design document when they get to work. What's your high level outline for a generic design document? I know we could rattle on this for hours, but just very quickly, what are the critical sections that every design document has to hit?
First, define the problem. What is the problem that you're trying to solve? Sometimes you get some people that come to you with a design document and, okay, it's a pretty diagram and this is a pretty story, but I have no idea what you're trying to solve. So I think defining the problem well, it's a very important aspect. What are your requirements? What is the problem?
Sometimes even I find people that come with this very long list of use cases and that doesn't work that well. You need a statement, a summarized statement that I can read and I can say, okay, this is a long list of use cases, but this is basically what we are trying to do. And that's defining the problem.
At least what I do, my thought process, is that I try to define what are my high-level architectures for this? What is what comes to my mind? And probably discuss what is the individual phase of putting together this versus the collective phase. I try to find what... my alternatives? What are my risks? What is the things that I'm afraid of? And I start figuring this out until I end on some type of architecture that actually satisfies me.
And then I like to tell the story of that architecture. And normally I have one or two pictures and one simple piece of text, and then I have alternatives. It's like, hey, by the way, I thought about this, but I don't think it works because XYZ. I thought about this other thing, and I don't think it works because this other reason. You know, I think that's the minimum that I need to actually start having a brainstorming or a conversation with a group of people.
Yeah, you definitely hit on the important ones. My list is pretty similar. I think there needs to be some kind of an introduction and a problem statement. What are you solving? What's the situation? And what problem are you solving? I like to explicitly call out your goals and constraints.
But again, that's very similar to that initial statement. But then you hit on the two most important things that sometimes people only do one of these, which is you need to elaborate on all the different alternatives that you thought about.
And then you need to dive into what your chosen solution is. I know that sounds really obvious, but it's very common that people will come with a design document that basically just does one or the other. They either take their chosen solution and just flesh out that, and they don't even talk about what alternatives they... thought about and dismissed. Even if those alternatives they dismissed out of hand, or even if they're fairly obvious, it's always worth calling out what those are.
Sometimes people do the opposite. Sometimes people put a design document and they'll have a bunch of options, and then they're basically looking for the design process to help them select one. That's great if people are going into the process expecting to get direction and get feedback, and that's okay. But I always tell those people, you need to have one you're leaning towards. You're the most educated on this problem as of now. Maybe, maybe not. But oftentimes, you know more than anyone.
else at this company about this problem. What are you leaning towards? What are you recommending? What are you thinking about and why? It's okay if you're not 100% sure. But put what you are leaning towards and put why and we can assess all that. But I think those two elements, what solution are you leaning towards? And what are the other alternatives that you considered? That's basically it.
Yeah, when I think by the way of problem statement, it's a good idea to think of this explicitly, but I'm also thinking on risk, constraints, limitations, etc. And what you mentioned about leaning towards one of these approaches, and I also agree with you. A pet peeve of mine particularly on these documents is that
Don't make me read the ones that you are discarding first and put the one that you pick at the end. Please make me read the one that you are leaning towards first and then the ones that you are discarding and why you are discarding. of that. You find yourself reading a bunch of things and realizing, okay, what is going on there? And when you get to the end of the meeting, you realize that the one that is actually being picked up or wants to be discussed is at the end.
To be honest, I don't care so much about that, like what order you go in, but it has to be clear what you're recommending and why. There's very rare cases occasionally when you're going into a meeting and you are expecting people to help you choose. And in those cases, you need to narrow it.
down even more aggressively. You need to have like... two options and have people choose between those i remember specifically one design review that i sat through and there were like seven or eight options and each of those options had like sub options and we were getting into the end and we're like
Okay, so are we leaning towards 4A or 7B? And it's way too many decisions and way too much complexity that you're expecting out of the discussion itself. Option paralysis. You have too many options and you don't know what to do or what to take. Yeah, I agree. You have to go to those meetings with an initial strong opinion. And, you know, it may be wrong. That's fine. In the meeting, the conversation may lead you into another direction.
into an option that is not even in the document, but into an option that is in the alternatives that you discarded because you had some thought process there that was not correct. That's acceptable. But I think what this section has to show is this is the option I'm leaning towards. why I am leaning towards it, why it satisfies the problem statement, risks, constraints, etc., as best as possible. What are the downsides of this option that I'm leaning towards? What are the risks?
The other options that I'm discarding is like, okay, I'm discarding this and why I am discarding it and this other one and why I'm discarding it. That's at least the minimum to have a reasonable conversation. I also would say be very careful with templates.
templates tend to be misleading you can find these templates of design documents that have 3 000 bullet points or different sections of whatever and stuff that needs to be covered and they become checklists you end up filling out this form basically Yes, and that deludes actually the reason of being of a design document.
And I'm not saying some of these sections are not relevant, by the way. Some of these things are important. And you may be able to look at them and just speak and say, OK, this particular project has a very important operational constraint. So I need to actually talk about the operations of this thing. Yeah. You know, specific teams or companies can have specific checklists or templates that they've developed and found to fit their particular situation. I've seen those exist and work.
But your general advice to basically don't over rely on this, you end up leaning on the paperwork as like a crutch. Yes. And another thing that is very important is that you don't have to have a perfect document to have a discussion. Remember, this is not a waterfall process necessarily. This is an iterative process. So you need to have a document that is good enough.
as quick as you can to start socializing it and having this conversation with people and having feedback and starting understanding the direction and what direction you are not going so you can simplify there and what direction you are really going so you can dive deep a little bit more there.
The sooner as you have something that you can socialize and talk to people, the better. It doesn't have to be perfect. It doesn't have to be 100% complete. Find that good enough, bad, and limit, and start the process. And it's not going to be the first, it's not going to be the last conversation.
Maybe at the end, you do have a rubric stamp conversation where you say, okay, after two or three discussions, we got to this. Does anybody have any final words to say about this thing? Maybe that's the rubric stamp. At that point, you have gone through several discussions. Something that I would like to add is that, to me, a design document is selling a story. Same if you think of user story.
when you have requirements, are telling a story and the journey of what the user is doing. To me, a design document is telling the story of how the system is going to behave in certain circumstances. What's the system going to do? It's very important that you think when you're writing these documents and design meetings on how are you selling this architecture or this story? How are you telling the story?
And there are a lot of strategies. To me, I'm a very visual person, so diagrams help a lot. I consider that having proper diagrams in a design document or where you are trying to socialize or share a design is very important because what I found is that I tell the story around. diagram. I basically say something like this. A user comes here and it sends a request.
And if that user is not authenticated, then we are going to redirect the user to this other service and page where it's going to go through the authentication flow, which works like this. And I'm telling the story. You send this to the server, server sends this to you, and so on and so forth.
And then eventually you go back to the main page and you send the request again. And then the request goes forward. And then when you take it on the service, you are going to write this to the database, put this message in the queue, and you're going to tell the customer that you got the request. And then in the background, this queue is being processed by this other component that is doing x, y, z, and so on and so forth.
I'm narrating, I'm telling the story of what's happening. And I have found that to be incredibly effective to communicate what's going on, to create clarity and so on and so forth, and to sell the design. You basically know when you're able to detail. what's happening in every step with simple words, which is also important to sell this.
I think that's really important. I mean, I think what you're talking about is narrating whether it's verbally or in written form, but going through an end-to-end flow. When I interview people and do system design interviews, this is exactly what I turn around and ask them to do. I ask them, walk me through.
a use case, walk me through what happens. Sometimes people have these designs and they just throw up a bunch of boxes and arrows and stuff. And it's like, here, here's my design. No, the design is actually in understanding how those components interact with each other. And so this story that you're talking about is exactly what you need.
It's not just what these things are and what connections they have to other things. It's when this happens, then these things happen. That's a really valuable aspect of communication. Yeah, and you see it in interviews, as you mentioned. This is a big pitfall in interviews. People start throwing a bunch of boxes and arrows, and here's the design, and okay, but how it works. How this fulfills the requirements. What happens if a user goes and clicks the button? And I even heard a mentee.
We went through this process, raising awareness into the direction. And it's like when I asked him to tell the story and he started actually putting that effort in telling the story, he started realizing that a bunch of arrows on that diagram were actually wrong and a bunch of boxes were not needed.
So I think it's an important factor. It is also easy when you're trying to have conversations about your design with different audiences. When you're talking with a product manager, you're talking with an executive. It's not about, hey, here's this very complex diagram.
with a bunch of technologies together, and this is our design. As you're telling a story, hey, the use case we want to fulfill, the most important thing is this, and the risks are this. And this is how we believe this design actually works, and works around the constraints that we have. And you're telling that story in simple terms.
I think it's incredibly powerful in that sense Another tip that I'm wondering if we can share with people is, and this is a common thing that I've heard or even experienced, but I'm curious, what would you say to someone who wants to spend more time on design, but feels like they can't justify it to their management or they don't.
have time available in their sprints, in their planning schedule, whatever. They don't feel like they have enough time to focus on designing. What best kind of advice can we give to someone like that? I think it's a bit of a fuzzy and gray area in some aspects. I can take it in different ways. It's that you really don't have enough time to design but also you need to realize that you cannot design forever.
There is a moment in which you need to switch from design to execution. And maybe it could be one of these cases. That's what I would like to try to figure it out. If it's one of these cases of somebody's trying to over-design something because it's trying to cross all the T's and all the I's before jumping into the Y.
and started coding, and that's not possible. There are things that you're going to have to figure it out on the way. It's definitely a hard question, a hard situation. You need to find the right balance. Escalate. talk to your senior engineer or talk to your principal engineer if you have concerns be very specific on these concerns it's like why we cannot start developing right now tell me what we don't know
Tell me what is the risk. If you can also communicate and articulate properly the risk of why not and what is what we really need more time to dive deep, then you may get that extra time because, you know, nobody's actually going to drive.
100 miles an hour towards a wall, knowing that there is a wall and you're driving 100 miles an hour. But if you cannot communicate that properly, your manager may say, well, I really don't understand your concern. We really need to keep moving. I think communicating is a very important aspect here.
Or in some cases, your manager may be okay with the risk of driving towards a wall 100 miles an hour, you know, and say, okay, if this backfires and this goes wrong, we're going to figure it out later. I'm willing to take that risk. You have been probably in those situations in which you know there is a big risk.
going on here and you are raising the risk. But what comes back from management is like, yeah, we know the risk. We are willing to take it. And it's like, OK, you know, I did my job and you are going towards the risk. Eyes wide open. So be it.
I really like that answer, actually, because it hits on both cases. About half the time when I hear people express this sentiment, oh, we don't have enough time for design, maybe they truly do need more time and they truly do have those risks that they can think of. They just need to...
And so I think that's great advice. If you have concrete risks, concrete things that you're worried about that you want to mitigate, things like, I'm worried that we will choose the wrong technology. I'm worried we'll choose the wrong architecture. I'm worried that we won't get this API design.
right and some other team will want to integrate with us and it'll be awkward call those risks out and see what you can do to specifically mitigate them but if you can't articulate those specific risks or if it's difficult to or if they're in the future and abstract and vague
Maybe that's a signal that you've done all you can at this point. Maybe you don't need to spend more time in design. Maybe your management is right. Maybe these are risks that you can acknowledge. You can write them down and you can evaluate when things change. But otherwise, maybe you can move on with the imperfect information that you have at the moment.
Yeah, and you have to remember that there is always going to be this balance or tension between leadership, management and development in the sense that development is always going to be pushing for more resources, for more time, for stuff like that. And management is always going to be pushing for more. features and more productivity and going faster.
None is right and none is wrong. No side is right, no side is wrong. Both sides are doing what they have to be. And I have seen this pan out. I have seen developers struggling, trying to communicate a risk and management saying like, no, keep going. I don't get it. Just keep going. And then after a conversation with development, finally pinpointing what is the risk and finally finding a way to properly communicate the risk and communicating it and management saying like, oh.
Okay, now there is a problem and just flipping. So I think our communication aspect is very important. And I have seen it in the other direction. I have seen developers trying to over design something and there is no reason. Right. A lot of times developers are using the design process. to sort of mitigate their own feelings of, oh, I'm scared things are going to change or addressing uncertainty. And that's really what it can't do.
which they do. Things change, by the way, and you have to be aware of that. It's not a failed process necessarily if things change and you have to change your plans. Yeah, if I remember, and this could be completely wrong, but one of the key words of key phrases of extreme programming is embrace change. Stuff is going to change.
Okay, Damian. So this has been a really interesting discussion. I think we've touched on a lot of interesting aspects of a software design process. We talked a little bit about what is it? What's the whole high level goal? What's the whole point? What are some of the goals? how you should be looking to engage with this process, whether you're a junior, whether you're a mid-level, whether you're a senior or a principal or something.
Hopefully, people got something useful out of pitfalls and mistakes, the things to avoid, or the tips and tricks that we shared. This is definitely a topic that I think we could dive into in more detail later. I'd love to do a whole episode on design documents and design reviews. diving really deep into those. But otherwise I think this was a really good discussion.
Yeah, I agree. I think we could keep talking about this forever. And I definitely think we're going to revisit these topics in the future, maybe bring in some guests to talk about that. I'm really happy, actually, with the conversation. I think it covered a bunch of interesting things. I'm sure we missed.
also a few things. I would be interested to hear what the audience has to say. So if you are listening, just feel free to share experiences with us through LinkedIn, which is at least right now the platform that we're using for that, and we will be happy to read. and potentially talk about more of these things later. Yeah, great. Well, see you next week. Good to see you, Dan. See you next week.
And that's it for this episode of Bytes in Balance. We hope you enjoyed our deep dive into the world of software engineering. Thanks for tuning in. We would love to hear your thoughts, so don't hesitate to reach out. Connect with us on LinkedIn to continue the conversation or simply follow our updates.
You'll find the links in the episode description. We aim to release at least one episode a month, but with our busy lives, it might vary. Subscribe to stay updated and you might catch some surprise episodes when we're feeling extra chatty. If you are enjoying the show, please rate, review and share it. with your friends and colleagues.
It really helps us reach more people in the community. To learn more about the podcast, check out our website. The link is in the episode description. And if you're looking for more personalized guidance, we're available for mentoring through mentor crews. And there's a link for that too. That's all for now. Until next time, keep coding, stay sane, and remember, even when it feels like a total shit show, you got this. Thanks again for listening, and we'll catch you on the next episode.
Thank you.