Why Documentation and Terminology Matter?

In this episode of Definitely Maybe Agile, Peter Maddison and David Sharrock explore the critical role of documentation, terminology, and process definition in scaling organizational success. They discuss how leading companies like Netflix build strong cultures through well-defined terms and principles rather than rigid processes. The hosts dive deep into how architectural decisions, cultural transformation, and team empowerment all stem from having a shared organizational language. Through real-world examples and references to modern practices, they examine the balance between principle-based leadership and necessary process documentation in creating high-performing organizations.

This week´s takeaways:

• Shared terminology drives better communication and decision-making across teams and departments.
• Principles empower teams more effectively than rigid processes and controls.
• Leading with principles while maintaining essential process documentation creates the right organizational balance.

Chapters

• 0:04 Defining Terminology and Process Guidelines
• 12:05 Balancing Principles and Processes

Transcript

Peter: 0:04

Welcome to Definitely Maybe Agile, the podcast where Peter Maddison and David Sharrock discuss the complexities of adopting new ways of working at scale. Hello, dave, how are you today? Peter, how's it going? It's going well. It's been a little while since we chatted, so I'm looking forward to today.

Dave: 0:20

Well, you've been out and about. I believe being eaten alive was what I understood.

Peter: 0:24

That's all I'm putting in. Mos was what I understood. That's all my opinion. Mosquitoes are horrible.

Dave: 0:27

That's not a client. I should say right, no, no not at all. So what are we up to? What are we talking about? Actually, I know what we're talking about. We're talking about it's a really interesting, weird topic to talk about, which is documentation and terminology and process definition. From a view of it's really important and we should be doing more of it.

Dave: 0:49

So now that all our listeners are tuned out because nobody wants to talk about that, Well, I think we have to be super careful because of course, we're not coming in here as process improvement and process documentation. We don't need to define a software delivery lifecycle or anything like that. We don't need to define a software delivery lifecycle or anything like that. But we are coming across a number of examples where terminology matters. Understanding what your organization means by epic or feature is really important.

Peter: 1:17

Yes, yes, and making sure that that lives on beyond the people who find it and that it's a part of the how the organization talks about these things. And then having an understanding of, like, what makes it that? What? What does that definition mean? So, if I call it this thing, if I call it a feature, what is a feature? What? What makes up a feature? Is a feature? Three months long is it? Six months long? Is a feature something that has a named owner and acceptance criteria? What? What makes a feature a feature? What? What are the criteria? It needs to have to be fully defined. And like what do we make that up? Like whatever criteria we decide to put around it and that becomes a thing yeah, and I I think what?

Dave: 2:02

so where I'm coming I know you're bumping into this and you were sharing a little bit about the tools nowadays where, because they're basically infinitely configurable or they're not, you can have a definition of a feature or an epic in one part of the organization which is different to a different part of the organization, which automatically we can see is going to start creating misunderstandings. Where I was coming at this from is I'm reading right now a lot about cultural change and one of the things that I find interesting is the organizations that have strong cultures, that really create those cultures where you'd think they don't have process definitions and so on. And I'm thinking here, you know, there's netflix and bridgewater and a number of other um sort of companies that books will write about and say how you know, how open their cultures are. They actually spend a lot of time defining terms and then really educating people coming into the organizations and reinforcing for the people in the organizations the importance of that terminology.

Peter: 3:12

Yes, yeah, and that reinforcement is what makes the organization thrive. I mean, it's the be able to be aligned, even be able to communicate with each other across different organizational divisions. If we're all working towards the same thing when somebody says a word, everybody in the organization agrees that that's what that word means it makes it a lot easier for everyone to talk to each other and have a conversation. And the example you were giving is the one where we've got like do epics and features go, which one goes above the other? And if you have both in the organization, then it becomes really, really hard to communicate because they're different things.

Dave: 3:55

Well, and I think this is an interesting point it's almost like it's a forcing function in the organization that dramatically changes how that organization operates, and I think we sometimes get confused about what that means. So let me try and put a story together so that makes sense. One great example is we're trying to push more and more responsibility. We're getting decisions made in agile teams. As an example, and if, let's say, I'm a member of the enterprise architecture group, if terminology around enterprise architecture is well understood across the organization, if the information and and the principles that that enterprise architecture group uses to make decisions is is captured and communicated and teams are educated on it, I don't need controls to manage what the work, to oversee the work that's being done on the teams. I use enabling constraints and I can empower the teams because the enterprise architecture group knows there's knowledge out there and there are principles that are being used to guide conversations, decisions that are being made.

Peter: 5:11

Yeah, architecture through conversation, where we're continually talking about it and ensuring that there's a common language. People understand what the right things to do are. There's known design patterns that are available to people. We understand how these different pieces fit together. So the enterprise architects don't need to be involved in every single conversation, but they're creating an environment where the right things happen because of the easy things to happen and the information is available and they're thinking. One of the other critical pieces there is to think that the enterprise architects shouldn't just be looking at the technology. They should be looking at the people too, and so they should be understanding how my organization is the socio-technical fabric of my organization. How is that operating?

Dave: 5:58

I love what you said at the beginning there the architecture by conversation, because it's exactly replace architecture by nearly anything else right every day, and and that, in a sense, is what culture is. Culture isn't a set of rules and gates that don't allow us to do x but do allow us to do y. The culture in an organization is a mindset, it's a way of thinking, and you pick it up not by rules that tell you what you you know, the gates that control and bring subject matter experts in there to tell us how we should have made the decision. Culture is something where we're able to make really good inroads as to what we think would be the right thing to do, and we're looking for guidance. We're not looking for control or gates or approval. We're looking for guidance and feedback. Are we going in the right direction? Huge difference.

Peter: 6:48

Right, and we see this a lot in various aspects of our lives where we think about how do we make sure that the right things happen and that we do the right things? And when we look at any kind of system, we often have checks and balances and guidance or guide rails in place to say if we want to go do this, what's the checklist of things I need to make sure happen. Say, if we want to go do this, what's the checklist of things I need to make sure happen.

Dave: 7:14

So I'm just working with an organization, we're putting a product delivery lifecycle together, and it's something that continually challenges us as we're pulling this together is to avoid describing the process as some sort of fixed thing, because the problem, once the process is a fixed thing, is any modification to that documentation, update, communication and all the rest of it, and it's much more about trying to identify what are the principles or what are this, the, the, the mindset, the thought process that goes behind it and it.

Dave: 7:48

It's correlating really well with some of the books I'm reading about an everyman culture robert keegan and Lisa Leahy and everyone, one culture and everyone culture, and it's interesting they're using really great case studies where there's a huge amount of thought goes into how things operate, not in the sense of process, but in the sense of process, but in the sense of principles. And once that thought's been gone through, then those can be, you know, as you, you join an organization, you get trained, educated, communicated around that there's some sort of always an apprenticeship model, because it isn't just here's the process, read it and follow it. It's much more about here's the thinking, and what works really well for that culture is exactly what's going to work well in that architecture by conversation. They don't need a process definition. They need principles and guidelines and how to think about it.

Peter: 8:48

And I think that works where there's there's levels of this too. Right, because you've got there's levels where the principles we're operating under. This is how to start to think through the problem. When we're in the fuzzy definition space and architecture is a good example of this I'm thinking about how might I do this Like, how might I put this together, what might this look like before I even get to design, I'm thinking about what are the component parts of this at a high level when I'm looking at those parts of it.

Peter: 9:17

The principles are necessary. They help guide throughout the organization. We always want to be following the principles throughout. When we get to parts of the system where we do need to ensure certain things happen, we need some form of checks. We're always going to need some understanding of what's the bit of this thing that happens as a process, that we need to make sure and that has to be thought about. But we always want to make sure that we've got the principles to fall back on. To say, wait a minute, this practice we have over here doesn't correspond to the principles that we've said, so there's a disconnect here. So how do we then start to resolve the friction between these two?

Dave: 9:56

Well, and I think I mean, if I kind of take this full circle back to where we started the conversation, which is a definition of terms, if you like, the definition I think it's a really weird thing as an agile coach to get locked into definition of terms and thinking what is exactly going on here? Well, actually we're we're defining a mindset and a way of working, and that needs definite, a very clear definition of terms in terms of language that we're going to use, so that now I can have that conversation around architecture rapidly and in a way where both of us understand that when we talk about whatever aspect of that, we're talking about the same thing and given that it would be inappropriate not to bring up ai in any kind of conversation at all these days, if you think about, uh, large language models in which gen ai is a subset overlapped in the Venn diagram of that.

Peter: 10:53

But in a large language model, what it's doing, it builds a view of our environment. This is why it feels so interactive when we're working on them, because that language does drive that cultural view, because it creates a model that we're operating within.

Dave: 11:11

Yes, and misunderstandings and actually in the large language models definitely as well. But misunderstandings arise because we might use a phrase or a term and it is understood in a different way, and that's certainly something that actually we're really good at as human beings and ai's. These large language models can often, um, fall short in certain areas just because of context and and so on. Um, but they well, they're going to change, they're picking that up super fast. Um, I wonder how we're going to change.

Peter: 11:43

Like, if I look at the organizations that are really strong, kind of culturally, they spend a lot of time getting that clarity around those terms another interesting piece of this is the you need the principles to fall back on when the processes and practices are not going to cover the situation that you're in exactly. Yeah, so you, you need a way of saying, okay, well, I actually don't have a process for this, what am I going to do? And then you run into that situation. Well, okay, what principles am I operating under here? How am I going to approach this? What am I going to do in this particular situation?

Dave: 12:22

I really I'm just going to touch on another book. The book no Rules. Rules around the Netflix HR piece is all about having no hr guidelines but is all about the principles about how to make decisions so that people are empowered to make us the right decisions in the right context, and I read that is a book that I read about. Obviously, I've built my own company and I'm trying to build something that's similar. In the same sense, incredibly difficult to get it out there, like in in a in a real world environment, because because of the misunderstanding around terms in many cases, because we we expect different things, we expect to be told what to do in some cases and not told what to do in others, and we want clear rules just because it's easier or it's quicker or whatever it might be, and there's a really interesting dialogue conversation to be had around that.

Peter: 13:22

There is. There's an element as well that people are not always comfortable not having the more strict rules and understanding of what those things are. People can get quite uncomfortable operating where it's in a vague area. So people who are more entrepreneurial tend to be happier with ambiguity than people who are used to working within a structure where there's lots of things which sort of tell them what to do and it's very clear what they need to do next. Now we could go into a conversation about agency and whether or not the organization has removed that, and that's why they feel comfortable in that environment. But the reality is that some people are more comfortable, and just naturally, with the having structure around.

Dave: 14:10

You just reminded me, I'm just running a workshop later on this afternoon and earlier this morning, and one of the things that came up was if you're ambiguous about your requirements, the team has to spend time and energy figuring out what the requirements are so that they can go and build it. You get variation, innovation, if you like, but also you lose time. So that really raises this idea of one of the things is what aspects of our culture or what aspects of our architecture, by conversation, do we just need to define and make sure everybody agrees on it and educate them and make sure they versus what aspects are? We want ingenuity and variation and innovation happening in, in which case we want that to be principle driven more than you know, clearly documented. If that makes sense, and it's, there's no rule. What works in one organization is going to be different in your organization versus in my organization, depending on what we're wanting to achieve.

Peter: 15:15

I think it also varies by situation, even within the same organization, because, depending on what your requirement is, I may want you to go away and think about how to go about solving this in a more imaginative way, but there's a set of hard criteria that it has to do and there's no asking about that. It has to be able to do these three things. These other four to six go figure out what they should look like right, usual thing.

Dave: 15:43

how do you wrap this up? How do you, how do you define the terms clearly so that we can walk like communication has happened?

Peter: 15:52

I think there's an interesting one with the first piece is when we're talking about principles and processes and practice, and there's a balance to be struck between the two. Leading with principles and say so that we're all clear on what the principles we're operating under is a good way for an organization to operate. There's been a lot of examples of organizational cultures that have thrived under models that operate from that principles, and I've got examples where the opposite is true, where organizations have led with process and practice and become really horrible places to work as a consequence. So there's definitely examples on both sides, but you need to strike a balance between the two. There is definitely need to have an understanding of well-documented processes and practices, especially for certain types of activities.

Peter: 16:44

It can really really be beneficial, especially if there's conflict, for example, and principles are not always going to be the right way to solve that. It's good to have it very clearly documented what happens in these circumstances, so we're all on the same page as to what we need to do. So there's when we talk about these things. We often talk in general, as generalities, so I think it's key to bring that piece back around. So that would be my first sort of takeaway is striking the balance, but leading the principles, I think, is a good. Uh, what would you add to?

Dave: 17:14

that I really liked the phrase that you mentioned and this stuck in my head about. I think it was architecture by conversation. I'm hoping I'm like remembering that correctly. The reason I like that is because it's it's almost like if I was to pull that down to the underlying bits. It's processed by principles, in a sense, and that architecture has some very rigid, very strong pieces that we have to kind of get in place. But the conversation that has definitely so much value to have where it's principle driven, it allows us to step away from controlling into one of empowering.

Dave: 17:54

And I think that's an unintended consequence of if we don't fully understand where we have to define something and where we don't, we end up in a controlling environment because we're not confident that that information is communicated out. So that's one thing. Is that just architecture by conversation? So that's one thing. Is that just architecture by conversation? And I think the second thing I kind of take away and that kind of kicked off part of this conversation is the amount of thought that's required to go in and define certain terms, and I don't spend enough time to both think through and then get buy in to certain terms, Like if I just think of the phrase prioritization. As I'm talking about this, I'm just thinking prioritization and understanding the consequences of that and what it really means if something has priority versus it doesn't have priority versus it doesn't have priority. There is a really in-depth conversation to have there, because if we have a clear definition and we all agree on it, then it removes a lot of the conflict, disagreement playing that can go around the site.

Peter: 19:05

Yes, I think that last one is a critical one. I've seen that trip a lot of people up when people are not in agreement. Something is a priority, Absolutely.

Dave: 19:16

Yeah.

Peter: 19:17

Okay, Well, thank you, Dave. As always, it's always a pleasure to have these conversations and I look forward to next time. Peter, until next time, Thanks again. You've been listening to Definitely Maybe Agile, the podcast where your hosts, Peter Maddison and David Sharrock, focus on the art and science of digital agile and DevOps at scale.