Technical Design Documents

[00:00:00]
>> Now for the last at least, lecture topic of the day. And this is actually my personal favorite, I never thought I would say this. It's so weird to say that you love documentation, but I do. I'm gonna show you guys the power of TDDs. And if you don't know what a TDD is, don't worry, I'm gonna explain it to you.

[00:00:21]
So TDD is basically a technical design document. A technical design document is a document that describes how a piece of software will be implemented, and how it will work. Typically includes detailed information about the system's architecture, modules, interfaces and data structures as well as information about any external dependencies or required resources.

[00:00:42]
Spoiler, before I go any further, does it say anything about using technology? [LAUGH]. No. There's a reason for that, again, because we want to start with the problem and we want to use the right tool to do that. Hopefully, the TDD will help us get there. So as I said, basically, a TDD in summary is what we want to accomplish, right?

[00:01:07]
And it's how we're going to accomplish that and it's really as hopefully as simple as terms as you can possibly get. You want a technical document to be readable by pretty much anybody in the company. And I really believe that writing documentation itself is like its own art.

[00:01:26]
You can write technical document, two different ways, and one will get approved and one will get thrown out the window and they can be exact same problem. But how you write it, how you portray the issue, or portray the thing to the person reading it what's actually majorly important.

[00:01:43]
And this is why technical design documents can be so powerful is because they can literally be the swing factors in any kind of decision making at a company. And as I said, a technical design document is used as a guide or used to guide the development of a software system and can be used to communicate the technical aspects of the system to the stakeholders and developers.

[00:02:10]
So as I said, it requires you to be able to convey what you need to. But what happens in a scenario where you're trying to sell something so big, that you literally have to get business involved? How do you do that? Well, technical design document can still accomplish that for you.

[00:02:34]
It really can. You just simply change it so that the stakeholders also can get buy in through it. Putting information in there related to how this is gonna save us money, or cut down on this or that it sounds really silly but, hey, business loves money and if you can show them how they can save it, they will buy in very quickly.

[00:02:56]
And sometimes that's all you need. Another thing about technical design documents is it's about who you're writing it for. Business also normally doesn't really care about a thesis on why you think we should use Kubernetes. They normally just care more so on, hey, what are the hot points and why should I care?

[00:03:17]
So sometimes the technical design document can be paragraphs. Sometimes it can be much larger. But it is really used to communicate the technical aspect to other stakeholders or developer. So we gonna start with your first technical design document. Now, as I've kind of said already with DevOps from at least my experience, there's no real standardized way of writing documentation.

[00:03:51]
You could try and get as close as you can but the reality of it is you're still gonna be in your own. We're all just trying to figure out how to communicate what you're trying to communicate to people. The best advice I've ever given was to focus only on the specific issue or problem.

[00:04:08]
I started out writing technical design documents where I would start going down a bunch of different other paths and then I'd have this huge thing and then I'd hand it over and then they'd just be like unreadable. [LAUGH]. So having clear and concise focus on the problem and what you're trying to solve is super important.

[00:04:27]
Asking yourself the problem, what is the problem, right? And tell a story around that. Set proper boundaries if you need to and include an out of scope section when you discover items outside of the current issues problem resolution path. And that's really important. If you are working with something that's got tons of technology around it and things like that, you really have to set your scope.

[00:04:52]
[LAUGH]. Otherwise you might find yourself in a scenario where, you have a bunch of creep as we call it of different issues starting to come in and things like that. And if you write a technical document that basically makes you write three other technical documents, then you might have just discovered a whole other problem that you can't even get to until you first deal with those other one.

[00:05:13]
Another thing that's really powerful about TDD is to apply existing practices to problem solving with the organization's already agreed upon, right? So if you use the three W's strategy to solve your problem at a company, then nobody should be able to argue with you your technical document was written around those strategies, right?

[00:05:31]
Again, DevOps is very much about communication and getting people interested and open minded to what you're trying to do. If you find yourself in a circumstance where that's difficult, leaning on things like this, the three W's, or the things like that can be super helpful to just state your argument and not really have to deal with as much pushback.

[00:05:53]
And this can be anything, it can be, we decided to do this or stick within these terms. It's just making sure that you're re-establishing what the company has already agreed upon to help you with your argument. So I did do a little bit of a breakdown for you on what I think are some helpful things when writing a technical document.

[00:06:22]
For starters, what problem are we trying to solve? That should always be there. As a matter of fact, you literally can write that as your first header [LAUGH] if you want always. If you do not know what problem you're trying to solve, close the laptop and go outside.

[00:06:36]
It because you're not ready to start solving that problem yet. You really need to be able to know what you're solving and honestly you can save yourself a lot of time by just simply asking yourself that question first. The other two are gonna be optional, but I do think they are pretty helpful, which is asking yourself, what is the current process, right?

[00:06:57]
How do we currently do things? Break that down. Look at it. Understand it. Do you know how we're doing well? Do you know how we're failing? Does the company know how we're doing that? And to give you a really good example of this, I was tasked at my company not too long ago to basically revolutionize how we do front-end deployments.

[00:07:20]
Because we don't want to have our front-ends in containers anymore, which is in there right now. So I sat down, wrote this huge technical document on how we could get ourselves there. And about halfway through what is the current process, I thought of realizing that there was a lot of organizational decisions that were made, and that's why we are where we are.

[00:07:41]
So, I guess what I need to say is if there are decisions that have been made outside of your scope, but it's related to what you're working on, those can be very impactful. In my circumstance I found out that we actually have a hybrid scenario where we have back end teams that work together to create products.

[00:08:03]
But then front end teams are completely isolated. So if you've ever worked in development and you think about teams that have their own silos for every project they work on but then your back ends are all collaboration, you have completely different fundamentals on how things are being built.

[00:08:20]
You have teams that are focusing on very small specific problems and technologies and then they don't care about sharing those technologies or anything like that, right? Versus back end or other parts of the infrastructure where those are very well shared, right? What do you do? That's up to you.

[00:08:36]
In my circumstance, I made the plain argument which is a tough one to sell which is, we need somebody there to do that? Basically we kind of realized that we didn't have a principal engineer somebody there that was guiding front end like we had in back end. Again, what is the current process can be massively powerful with that.

[00:09:00]
What are the requirements? This is another thing that can help you a lot. So again, for example, if you're trying to propose using a specific type of technology, maybe to solve your problem, again, not what I would suggest, but if it is something go like, okay, I know I want to use this, whatever.

[00:09:17]
Does it fit your requirements? I know I've been making fun of Kubernetes, but it's honestly a really good example. Because a lot of times Kubernetes is not normally within the requirements of what actually just simply needs to be done. And I would almost bet that if you really sat down and said like, what are the requirements of what I need?

[00:09:40]
You might notice you could probably solve it with a bunch of different solutions, not just one. The last one, and I do think that the last one is very important, is, how do we solve this problem, right? If you know what problem you're trying to solve, then you should be able to propose some type of solution to it.

[00:09:58]
And if you can't, then your technical documents not done. [LAUGH]. And you first need to figure out how to solve this problem.