Video Summary and Transcription
As a software engineer, achieving success in software development requires having a strategy and tactics. However, obstacles such as unnecessary meetings and miscommunication with clients can hinder progress. The methodology used in software development is more important than the programming language. Soft engineering is about understanding strategy and tactics and finding efficient solutions to problems. Software architecture should be aligned with business goals and objectives. Documentation is important for scalability and avoiding miscommunication, but finding the right balance is key. Task efficiency and simplicity in code design are crucial. Embracing simplicity and improving documentation can lead to better software architecture. Communication and collaboration between management and engineering teams is essential for making informed decisions.
1. Introduction to Success in Software
As a software engineer, I want to talk about achieving success in software development. We often try to measure success in various ways, such as the number of tasks completed or the amount of code written, but these metrics don't accurately capture what makes a good software. Instead, having a strategy and tactics in software engineering is crucial for success. Unfortunately, many obstacles, such as unnecessary meetings and miscommunication with clients, can hinder our progress.
♪♪ ♪♪ Hello, everyone. Good evening. It's amazing to be here to talk more about software development. As you can see as well, I'm a software engineer. And that's the main reason that I don't buy T-shirts since for a long time. So I'm super glad to have a new T-shirt. This way I can hold for maybe five, six years, and then I can move on to a pyjama and finally find a new T-shirt as usual.
So today is not to talk about my dress style, if I have one, I'm not sure, but it's more about talk more about success. Everybody wants to have success in software, right? And the question is how to achieve that. And I need to do it with only 20 minutes. So I have no idea how I can do that. And to be honest, my daily is much longer than that. I don't know why, but what's supposed to be shorter is not shorter. But anyway, let's do my best as possible to convince you that having strategy and tactic inside software engineering is good for us. It's a good way to achieve success when talking about software engineering. And naturally, as I said, everybody wants to have success inside software, right?
So I want to do a good software, I want to deliver a good software. Come on, the software industry is here for over almost 100 years. But how to measure a good software? How to have an idea to understand if I'm doing a good or a not good software? And for a long time, we tried different strategies to make it possible. Naturally, let's measure by the number of tasks that we're doing for a long day, for one month, for weeks. And naturally, it's not work. And then we have the data metric, we're doing deploy faster and faster and faster, but it won't work anyway. And the last one that we tried, and unfortunately we failed, was measure us by the number of commits and then number of code. So if I'm doing more code, that means I'm doing a successful job. And unfortunately, it is not true as well. So when you go to several reports, magazines, we can see that result, unfortunately. So it's like this one here that belongs to Forbes, 16 obstacles to have success in software. I can summarize the 16 and only four. Basically, we do have a lot of meetings, a lot of discussions to deliver what the client does not want. It is sad. It's like I'm going to a bakery here in England, order a street food, I guess that's the right name, or maybe go to a pizzeria and order a vegetarian pizza, wait for three, four hours because the kitchen are doing several meetings, and then they give to me a salad.
2. Challenges in Delivering Client's Requirements
We often focus on discussions and meetings, delivering complexities instead of what the client actually wants. This lack of focus leads to poor collaboration and a disconnect between software architecture and the goal of the project.
So it's terrible. It's awful, right? So we are doing several meetings. We are discussing several things to deliver what the client does not want to. And how sad is it? Especially because we are doing several discussions, we are doing several meetings, several plannings, instead of delivering what the client want to, we're delivering more complexities. Yes, sometimes we spend more time discussing microservice than business requirements. And the consequence of that is naturally the poor collaboration between teams and product. So we are discussing a lot around software architecture perspective, but we forget why we are doing that, the meaningful reason to do that, to achieve that reason. And you can see that in a second magazine, this common code. So it's common for developers to deliver a product that does align with the client's perceptions.
3. Importance of Methodology in Software Development
We often focus on discussions and meetings, delivering complexity instead of what we're supposed to deliver with software. It doesn't matter the language, what matters is the methodology. Let's discuss strategy and tactics around soft engineering, comparing it with history, especially military history around engineering.
So we are doing a lot of meetings, we are delivering complexity, and we are not delivering what we're supposed to deliver with software. And it doesn't matter the language, right? So I can do mistakes with Java, I can do mistakes with JavaScript, Rust, or even a new technology. It's very often people come to my office to discuss, OK, Otavio, right now nobody understand that code. And to make it possible, I got an amazing idea. I will take my code, move to a new technology, because after that, everything going to be all right. And sadly, it's not true, because after three years, guess what? Nobody is capable to understand the language again. Nobody is capable to understand and move the product forward again. So it doesn't matter the language. What matters for us is the methodology, right? So that's the reason that we're here. We need to discuss more around strategy and tactics around soft engineering. And naturally, when we talk about soft engineering, the youngest brother of engineering is natural that we compare with history, especially the military history around engineering.
4. Strategy and Tactics in Soft Engineering
Soft engineering goes beyond code, it's about understanding strategy and tactics. It's the application of empirical scientific approach to finding efficient economic solutions to any problem using software.
Take this here, for example. We do have Julius Caesar, who wants to cross a river. And to make it possible, he finds one way to build a bridge in less than 10 days. And based on that bridge, he could cross over 40,000 soldiers. The goal here is not about to build a bridge, but to cross a lot of people to the river to attack Germany. So that we do have also with soft engineering. It's important to us to understand what is strategy and what is tactic inside soft engineering.
And when you go deep on several technologies around soft engineering, the first question is, Aran, what is soft engineering? How can we achieve success in one thing that we don't understand what is that? It's only about code. Hopefully, you understand not. Soft engineering goes much beyond the code. So there are several terminologies. My favorite one comes from this book here, The Modern Soft Engineering by David T. Foley. And he mentioned that soft engineering is the application of empirical scientific approach to finding efficient economic solutions to any problem, of course, using software. So it's not about writing code. It's about solving problems. And naturally, when we talk about software engineering, we talk about strategy and tactics in another way.
5. Software Architecture and Strategy
Most of the time, when we talk about software architecture, we're talking about strategy and design. There's no unique definition for software architecture or design, but it's about being close to the business and making goals achievable. Software architecture is the reason and strategy for development, with trade-offs and no bad practices. Understanding the reason behind technology is more important than how it's built. Maturity models help us set objectives and achieve metrics.
Most of the time, when we talk about architecture, we are talking about strategy. And when we talk about tactic, we are talking about design. And that's fun, especially because we don't have a substantial terminology or unique definition to what software architecture is or what is soft design. Take here, for example. I do have a couple of books as you can see, and every single book has a unique definition around software architecture, a unique definition around software design. So my favorite book here is just enough software architecture. And for this book, software architecture is a collection of software design. There is this book here by Simon Brown, the creator of C4 model. And software architecture, for him, is one thing or one software design that is really tough to change. So even with a hard definition about what is software architecture and soft design, we can see that mostly of the time, when talk about software architecture and talk about achieving success with that, I'm talking more about be close to the business. I'm talking more about, OK, how can I achieve and make easier to the business people to make my goals close and close as possible?
And when we go to that discussion, we can see also several definitions. This one here is my favorite. That belongs to the fundamentals of software architecture. And that's why I do believe that software architecture is more the reason and the strategy of having one way to go around development. So this one here, we do have two laws around software architecture. The first one is everything in software is a trade-off. So there is no silver bullet around software development. So if you're going to choose one technology, you're going to face some good points and bad points. If you choose another technology, the same thing. Indeed, that's the main reason of us when talk about software architecture, there is no bad practice. Especially because, OK, I can say that if I do multiple ifs inside my code, I can replace with a strategy pattern. But I cannot say that microservice is a bad pattern or monolith is a bad practice, because what's going to hold that is the context. So everything has a trade-off. Microservice has trade-off, monolith has trade-off. And the next step is the reason to do it, the strategy to create it, the strategy to build it is more important than how. If I understand the reason to create some technology, some software is more important of how I'm building this software. And to do a metric around that, that is why I do believe in maturity models inside our soft development. So the maturity model can help us to get direction where we are and where we want to go. We can achieve metrics for organizations that is super important for us. And we can set objectives, we can set requirements to make it possible.
6. Soft Engineering and Documentation
Make sure that your code is close enough to the business. Documentation helps with scalability and avoiding miscommunication. Too much or no documentation can be problematic. The ninth capital case highlights the importance of documentation. Strategies for documentation include writing it in code, having a changelog, and using open API documentation.
OK? And that I do believe around soft engineering. So we do have our context, and our context is more about how we can be close to the business, how we can achieve the business requirements. And then we do have four points to take a look. Naturally, I do have only 20 minutes. I won't cover the context here, how to metricize business requirements, especially because I'm talking more about soft engineering perspective. But the point is, make sure that your code is close enough to the business. And based on that, we can check code design, tasks, documentation, and finally governance.
And every time I talk about documentation, people start leaving their rooms, especially because it's one thing that we don't enjoy enough, right? So we hate writing documentation to our code, but especially because presentation does not compile. Presentation is not enough, right? So presentation, documentation is something that we don't enjoy. However, if you don't do any documentation, how you can make your team scalable? I mean, think more about onboard process if you don't have any documentation. Think about the number of meetings that you need to do, because I'm not Jedi. I cannot read people's minds, right? So documentation helps on this kind of scalability inside your project. And of course, we need to understand that we need to go to a fair point of documentation. Too much documentation is a headache for you, but also no documentation is go horse. There are several reports about how and why having documentation. However, we don't have any report about the costs of having documentation. But we do have one case about how losing a company in 45 minutes because you don't have documentation. And probably, you know this case, the ninth capital saga. And of course, they did have several problems. They did have several issues, including, unfortunately, the misdocumentation to do the restore. And that is tough, right? I mean, if you ask your ninth capital how much is documentation, they were going to reply with, OK, the documentation costs us over $400 million in 45 minutes. And that's why documentation is important. And when we talk about documentation, naturally, we can cover the tactic and strategy around documentation. So write documentation inside your code. Make sure that you do have a changelog for your repository. For example, a new release, you can see clearly what changed, what was included, and so on. Inside your readme file, explain the goals of this repository, how to use and how to install. And finally, as we talk more about REST APIs, make sure that you are using any kind of open API documentation. Think more about scalability. As much documentation you do have, less meetings you need to face it.
7. Documentation, Code Design, and Task Efficiency
Save time with documentation. Use the C4 model for mapping technology. Communicate clearly. Aim for simplicity in code design. Understand the importance of task efficiency. Combine task coverage with mutation testing.
So you're going to save people's time doing documentation. And as I said, the tactic inside the code and strategy mostly around attach your perspective. So the C4 model by Simon Brown, that takes the TechRadar to mapping the technology that we use inside your organizations. Attach your decision records. This way, you can make sure that you took the decision, you know the reason, you can measure that decision by trade-offs. And the last one is naturally doing clear communication with forums, Slack channels, and things like that. Remember, less meetings, sometimes it is code.
And when we talk about maturity model, I need to talk quickly here. So we usually start with known documentation, and then you can move forward to do the code documentations, then repository stage documentations, attach your documentation, and finally explore more the DocOps. What does mean DocOps? So basically is, as soon as I merge my documentation, my documentation is available to see and read. For example, you can use AskDoc inside your Readme file to help people to understand how to use and how to style that code. inside your organization. Okay, move on to the next topic, around code and code design.
There is this amazing book called The Philosophy of Software Design, and he has a good definition around the main difference between a coder who goes more to the tactical, that means work to get things done, and the strategic way. So the book called that person a tactical tornado, because he can do a code faster and faster, but every code that this person touch, nobody understands anymore. So it's become a nightmare. And long-term, it's impossible to read and understand any code around that. So, and that's the main goal of avoiding complexity inside your repository, inside your architecture. So it's natural we're starting with patterns, we want to learn, we want to apply as much as possible, but at the end, our goal must be fight to get more and more simplicity inside our code.
Okay, so in the code design maturity, I will need to go quickly here, so sometimes I don't care. And then I can move on to the simplicity or the ultimate stage of sophistication by Leonardo Da Vinci. So the simplicity is the way to go, writing good and simple code as much as possible. Then we do have the tasks, it's one thing that you can do and explore as a teacher inside our organization. So it's not only about the task coverage, because it's important, it's crucial, but you need to measure how efficient this task is. Okay, so you can combine that with mutation testing. So as Java developer, my background is Java, so I'm using PyTask, but naturally, in your tool, you can use whatever you want, but my advice for you is to combine task coverage with mutation test. It's not about coverage only, but, of course, how efficient those tasks are. And talking quickly about the maturity model of tasks, so known tasks, unfortunately, it's happened, so you can move on to unit tasks, integration tasks, task coverage, and finally, the optimized tasks. That means the combination of the task coverage with mutation tasks. This way, you can define the minimum requirement to move your code forward.
8. Code Merge, Governance, and Simplicity
Merge code with at least 18% coverage. Importance of governance. Use tools for easier governance. Maturity levels of governance. Get closer to the business and embrace simplicity.
So I only can merge this code if it has at least 18% of coverage with my code. And this task must be with efficiency. The last one that I'm going to cover today is about governance. Yeah, sometimes we look at it as a red flag for us, we don't like it, but it's necessary, even for startup. And the reason is mostly long-term, because we leave organization, but the organization should keep doing this code. It doesn't make sense to every time recreate or redesign the code. So to consistency, to re-specification, to efficiency, and naturally to work with collaboration.
The efficiency around... This is the father of ChartTPT, right? The main goal of governance here is to use several tools to make your life easier. So this is a simple sample of optimized governance. The SAS, so the Static Analytic of Security. This way, you can avoid SQL injection, HTML injection, and so on, just using automated tools. So to use some tools to upgrade your dependencies, especially to avoid any CVE breach, and naturally, check style. So if I'm using some missing alignment, if I'm using some tools that I should not use, or I'm using some API that's deprecated, you can avoid all of this kind of thing with governance.
And the maturity of governance, so none. Then move to code, code repository, inner source. And evolutionary governance, where everybody can participate, can join, can help to create the governance inside the organization. So because the main points of the software development to achieve success is naturally, one, get closer to the business, and the second point is to do that with simplicity, because requirements change. But I need to be able and be ready to change with the business itself. That's all for today. My name is Otavio Santana, so mostly Java, and hopefully you enjoy, and see you around.
Improving Documentation and Architecture
Recommendations to improve documentation. Focus on the client's essential needs. Simplify the architecture based on context.
And the first question is, in many companies, products are documented, but this documentation makes no sense because it's poor quality. Can you recommend some principles to improve it? Yeah, that's a good point. So my first recommendation is be close to the business. First one, naturally. And there are several methodologies to make it possible. For example, you can do the storm, where you, the engineering team, and the product team can write documentation together, especially at the beginning. And also, they start telling domain, where people together, as well, can define the business technology inside the product itself. So those two are amazing. My favorite one is to start telling, especially because when we talk about human kind, we kind of enjoy telling history to somebody else. So if you go to Amazon right now, you can see the book, Start Telling Domain, where you can see the methodology and how you can apply that with DDD, Domain Driven Design. So for software developers, the Start Telling Domain is the best one and super close to the code, as well. So based on that, you can define the bounding context. You can define the mapping context and also define the entities and things like that. Thanks.
The second question is, should not we focus on the essential need of a client instead of what they are asking for? Otherwise, they always ask about faster horse. That's a good discussion. But sometimes, what we do, we try to guess what the client wants and forget to ask the client itself. So I took this data from Phobos, from Gartner, as well. And the majority of the time, we have failed to understand what the client wants. So the 16 obstacles, as I mentioned, was about we are doing something that the client does not want to. So we cannot really work together with the product, but we need to pay attention because work they do a faster horse is do, I don't know, food instead of horse, okay? Okay.
What do you think is the best architecture for libraries like React as it gets messy, as it scales? The best architecture for libraries like Reactive? Okay, I'm not. I'm mostly a back-end engineer, so my recommendation is the best architecture is the simplest one based on your context. And what do I mean about that? So if you're starting a project, go for monolith. It's gonna work in any technology. I'm a Java developer most of the time. I did it with Kotlin, as well. And every time that people start to go to microservice first, we get a huge nightmare because usually it's overengineering about what we're supposed to do. So go simple, baby steps, and keep evolving with that. Yeah.
Managing Frontend and Backend Architect Decisions
Ask for a bridge between management and engineering team to improve visibility and understanding. Having someone in the role of staff plus engineer can facilitate communication and avoid coding blindly.
How to manage frontend versus having back-end architect decisions when frontend solutions are better understood by management? Because they are visible. It's time to ask for visibility inside your team. So in America, most of the time, we do have one person that is the bridge between management and the engineer team that we call staff plus engineer. This staff plus engineer is the engineer who has the job to be a leader and asking for that, especially because if the engineer team is not understanding what they need to do, we are failing as software engineer. It is a huge mistake. So my recommendation is ask for someone who is capable to be the bridge. Ask for this staff plus engineer person to handle that, ask him. So someone will be there to stay in some boring meetings and do these kinds of discussions and bring more of the management inside. Otherwise, we're going to code blindly, so it doesn't make sense.
Comments