Hello. Thank you so much for having me here. Super-excited. My name is Linna, thank you so much for the amazing introduction. I have been a product engineer for 8 years. In tech for about 10 and I'm here to talk about technical planning and more specifically about tech specs and how they can help you build more responsibly and collaboratively.
I also want to preface that a lot of what I will be talking about are mostly suggestions and it varies across different orgs. It's based off of my experience. And they've kind of been everywhere as well. So, take what resonates with you and leave what doesn't. Figure out what works best for your team. So, with that, there's a lot to go over. So, let's get started and talk about the purpose of a tech spec and what it actually is. So, a tech spec is documentation that you write prior to development of a product or feature to communicate a plan for how we can build it.
So, the keyword here is "Communicate." That implies that there are multiple people involved. We're not just writing this for ourselves. And primarily the audience is going to be other engineers. But it's also important to acknowledge that we don't build in isolation. We're not just code monkeys who generate code and then scurry away in a corner and like, cry. But we have other people that we are working with. We have other engineers. We have cross-functional partners. For me, as a mostly frontend person, I work really closely with designers and product managers. We work together to build cool stuff together. So, it's important to figure out how do we as engineers organize our work and identify what we need from other people?
And even though non-engineers are not necessarily the audience, they're a really important part of the process. So, how do we allow them into our planning process? You may also be wondering like why do I even want to write a tech spec to begin with? There are many reasons. It's always great to have a plan, especially if you're anxious like me. But by the end of it, you should be able to have better estimates to assist in roadmapping, which is very helpful for people that you're working with in product. Or people who are planning out what things to build. You'll be able to approximate feasibility or make informed tradeoffs especially with those cross-functional partners. You'll be exposing gaps and points of confusion. Especially with thing like product and design. Especially since as engineers we tend to get the more nitty gritty things and we can catch things that they might not necessarily catch. And at the end of it, you'll have a living document for engineers to discuss. And to reference in the future so that other engineers who come after you can understand why you made the decisions that you made.
And over time, your docket is going to develop and just change as you find more information. And identify all the things that you need to do. And all of this leads to fewer surprises and allows you to communicate more effectively with stakeholders and with your teammates as well.
You can also use your tech spec as a checklist to keep focused on important tasks and questions as well. So, for me personally, whenever I get really overwhelmed with all the things that I need to consider, all the things that I'm thinking about, I come back to my tech spec and I try to organize my thoughts somewhere in the doc and to figure out what my next actionable steps are. And that keeps me a lot more grounded. So, hopefully I made the case for writing a tech spec. I think most engineers would agree that it's a good idea. So, let's just go over what is actually inside of a tech spec and generally what the anatomy of one could look like.
It's also very important to note that your coworkers are probably very busy as well. And they may not necessarily read the entirety of your document. So, you want to format your tech spec to optimize for this. And to make the most important items towards the top of your document where it's easiest to find and you'll probably have the most eyeballs on those sections.
And you may not necessarily write all of this in sequential order as well. In fact, it makes sense to start writing and then go back into the earlier sections and fill in the blanks as you uncover more information and get more answers as well. So, this is what I generally use. But we will go over what is in each one of those sections in more detail. So, we'll start off with the objective. Which is essentially the introduction to your document that lets your readers know what we are building and why we are building it. And we don't necessarily have to rehash the product spec. Hopefully you'll have that linked somewhere so that they can read it in more detail. But we want this to be brief. Like two to three sentences just to prime our readers to understand what we're trying to do. And we want to focus on what the functionality we are building is. Like what is it supposed to enable us or our users to do? If you have doubts about whether the requirements that you got is going to serve that intended purpose, you should be talking to your teammates and asking yourselves, are we building the right thing? You should be on board with what you are building and your teammates should be as well. So, if there are questions, it's worth discussing. And figuring out solutions or maybe there's just something that you're missing. Just to clarify and get excited about what you're doing.
For things where there might be a lot of excitement around it and lots of ideas, it might also be helpful to put in what is in scope in are your project and what is not in scope. That way you're letting people know, like, hey, we've considered this. But there may be some sort of tradeoff that you are making. It helps keep your document more focused as well during discussions. And it also prevents the goal post from moving too much and preventing you from actually shipping something. And in this section, you also want to add links to relevant documents. So, product specs, design files. You might have like a tracking spec from a data team or something. But you want to share those files with your readers as well so that they have the same context and they'll be on the same page when they're reviewing your proposal. Just to give them more information.
So, next let's talk about release plan. This section should include instructions for release that are specific enough to hand off to someone else and they should be able to do it for you if needed. So, for example, are you use feature flags? Are you doing a full deploy? You should be putting that in here and like how you would actually like deploy it. We also want to explain what the rollout schedule looks like. Like when is this thing actually being released? To whom? If you have different variants? It's really important to tell people when things are happening and what is actually going to happen. And you may even have internal testing done before releases. Well, like if your company can test it before it goes out to the public. For all of these, you want to put in the dates so that you can keep track of when things are happening and to sort of gauge yourself as you are developing and seeing whether you need to adjust dates, whether you need to talk to stakeholders and figure something else. But generally, it's just good to let people know. And for yourself to sort of have a goal.
And I think most importantly, like is there a rollback plan? Sometimes things just happen. Emergencies just occur. You should be specifying what to do in those cases just in case like you're gone for some reason. You don't want to become a bottleneck. Someone else should be able to handle the situation as well if you just need to turn the thing off.
Okay. So, next section is open questions. And this is where there's a lot of ambiguity and things may be vague. It might be really specific to your project, or your company. But generally you want to figure out, yeah, like what things do I need to know? This is usually the most collaborative part of the tech spec, I think. So, some questions that you might want to ask are, are there decisions in flight that can change what you build? So, for example, a lot of our cross-functional partners may also have some sort of approval process that they need to go through. Are they through the process yet? Are there things that are more concrete than others? That's what you want to figure out. Or those with the questions that you want to ask that will help you figure out how you're going to build a thing. Like you need to be more flexible about the UI. Do you need to do something or confirm some information ahead of time? Or do you like just shuffle things around? And next, we want to ask if there are questions about the requirements. Are there things that you are just generally unclear about? Or are there things that are missing?
Something that I see really often is designers and product managers may forget to consider what isn't in the Happy Path. So, error handling. Those are things that are worth discussing with your partners as you are working that help build a more robust product. And just filling in the gaps. And lastly, do you need more context from other teams? A lot of times we might be building off of the work of other people. But do you know how to integrate those things? Do you know who to contact if you have questions about those things so, in this section, we're just trying to figure out a lot of questions. But I think it's also very important that we make friends and ask those questions as well. We're trying to get answers for these questions. And you should be updating your doc with the answers as you find out more information so that other engineers don't have to do the same guesswork.
So, I really like pairing with my designers to figure things out if something looks a little wonky or if things can be done better. Or you can leave comments in the product spec. I used to be really terrified of asking questions. But I think for the most part people have been really accepting of just like answering questions that I have and if you're scared, just push through it. Little -- little easier said than done. But over time, it will become easier. Especially as you are building those relationships with those cross-functional partners and your teammates as well.
So, good stuff.
And then let's talk about potential risks to your project. You know, like we can't always account for everything. But it's good to have a general plan. Especially for things that can be incredibly catastrophic or things where we feel like, you know, like there's a high probability or decent probability of something happening. But the effort that you put into this section is sort of up to you and your team. It kind of depends on how much time you have and how thorough you need to be. Like if your system is really critical, you might want to spend more time in this section laying out what could go wrong. But some questions that you may want to ask yourselves are, do you have any external dependencies. So, for example, are you depending on another team's work that isn't deployed yet? Or is still in development? Do you know who to contact about that? I think it's really important to add the status of it as well so you can remind yourself to check in and also to reach out to them as well so that they, you know, you're on their radar and they may have to prioritize things a little higher or if you can get them to prioritize it, that would be great. And are you using unfamiliar technologies or tools? Because a lot of times that's going to have some sort of learning curve. And that might end up taking more time. Or you might just realize that a tool doesn't fit what you were actually trying to do. You may even be trying to figure out what vendors you're using.
If you're still trying to figure those things out, it's worth putting that in here. And if some system that you are relying on can take down whatever you are building, it's also worth putting that as a risk in here as well and figuring out how we can mitigate that. And, you know, other things -- there are many things that can affect the quality, timeline, or stability of your projects and you should list those as well. And each -- and for each one of those where it's possible, you should be including ways to minimize the risk to just sort of make sure that nothing just blows up spectacularly. Or you can explain the tradeoffs that you are making. Because I think not all risks are the end of the world. Not awful them are catastrophic. And some of them have a higher probability of occurring than others. And sometimes, you know, you just want to make sure that you are making a sound decision if you are deciding to take on that risk and you want to make sure that people are also on board with that risk as well and you just to want explain your thinking around it.
So, next, let's talk about architecture. So, this is sort of usually the meatier part of the tech spec. But generally, we want to lay out the general approach for how we are going to build this thing. And sort of the desired end result. Like what does that look like? This is usually where we get a bulk of the feedback from other engineers as well. So, one way that I like to think about architecture, especially for thing like APIs and UI components is in terms of inputs and outputs. Like what data is required? And what comes out the other end? Tables are really helpful for organizing this since they're just a little bit more succinct and someone can just glance at it and just generally understand what you are proposing. We also want to organize this into smaller sections. Like where does it make sense to have mental boundaries about the entirety of the thing that you are building?
This can help you identify tasks later on. And also, help your readers understand your mental model so that they're also following what you are proposing as well.
And lastly, what systems are involved and how do they interact with each other? In those cases, I think diagrams are worth a thousand words. It's really nice having a visual that sort of tells the story of how all of the pieces fit together. What things are talking to each other. Just as a nice summary of all the things that you are writing in this section. I think it's also useful to use screenshots if you are building something that is more visual or like UI-heavy. Just so people can understand how you are mentally breaking down components or sections as well.
So, after we have this general idea of like how we are going to build the thing, we need to identify what the tangible steps are to actually build this thing. So, if you have trouble with this, something that I usually do is I look at subsections that we've define when had we were talking about the architecture and I break those down into smaller pieces of work. Usually small enough to translate into tickets for some sort of like project management system. And you don't necessarily have to dictate how it gets done. But you may also want to add inputs and outputs just so that, you know, we make sure that all the parts fit together as expected in case there are multiple people building all of the different parts and we just want to make sure that the interactions are correct.
You also want to talk about any blockers to the tasks. So, this can help you sequence your work. Because sometimes getting unblocked requires relying on other people who may not necessarily have the same priorities as you. So, you'll probably want to get ahead of that. And not leave it towards the end. And just be stuck and have to move dates.
And related to this, what tasks can be done in parallel? So, you may want to organize all of these things in different tracks of work. And figure out, you know, you want to answer -- if you have more teammates, will throwing more people at the problem make it go faster? And sometimes it's true and sometimes it isn't. But you do want to be able to answer that question to also be able to resource your project effectively as well.
So, we also want to talk about how much effort a task will take. And I will talk a little bit more about this because I think estimating effort is a learned skill. And also, like breaking down tasks as well. But there are many different ways of quantifying effort. And so, what I've seen previously are points, like if you're using Jira, T-shirt sizes, so, small, medium, and large. And in terms of time. And there are lots of people who will argue about what the right unit of measurement is. But you just want to figure out what works for you and your team. But something that is also helpful is figuring out how to convert whatever you consider effort is into time so that you can communicate with your stakeholders and set realistic expectations. But some other tips that I have for estimating effort are to pad a little bit more time for tasks where you may have unfamiliar dependencies or where it's a little bit more ambiguous or you aren't completely sure how to do this thing. You also want to allow time to write tests and for code review to occur. Just so that we are building something of high quality and it is robust.
You also want to revisit your estimates and calibrate. Like what tasks did you overestimate or underestimate? Doing this will allow you to develop higher accuracy and to take those learnings into the next project that you plan. And it's definitely a skill that takes a lot of time to develop. And it's -- it's kind of tricky and seems like it would be easy. But a lot of times people underestimate a lot. So, that's a little tip.
So, we've talked a lot about what is actually in it. Let's talk about the process. And again, this is sort of dependent on your team's needs. You should be tailoring the content and process to what works for you and your team. But some questions that you may want to ask are: What is your team size? How available are the people on your team? How much urgency is there around shipping? How much detail is useful in a tech spec? Especially if you have more junior engineers who may need a little bit more explanation. And what level of risk is acceptable? Because all of these questions help you determine how much sign-off you want in the process and how much time and effort you want to spend in planning. So, if you have a system that's more critical, you should be spending more time planning, probably. And, you know, like process can effect your team's culture. So, you should be setting the standards and the behavior that you want to see. And it's perfectly normal to iterate on this process as well as your team grows and as priorities change.
So, let's sort of go through like what might actually happen? So, this is just a hypothetical example. So, an engineer, you, might receive some documents from like product or design. Some people. And you want to review the requirements of what you are supposed to be building. And you want to translate that into engineering land into a tech spec. So, you want to start writing. And naturally, you're going to have questions. I don't think I've ever not had questions as I was trying to figure out how to build something. And that's fine. We can collaborate with the people that we work with and find answers. Or maybe you just need to spend a little bit more time thinking about it and like getting feedback from other people. And then you'll want to write some more and revise things. You'll probably go through multiple cycles of this and that's completely fine. And once you have all of the answers that you had -- or answer all of the questions that you had, you might be ready for review with other engineers. This can be a synchronous process, this can be an asynchronous process. Even if it's a synchronous process, you might want to send out your document ahead of time so that engineers can read it and kind of let it sink in so they can give you better feedback. But in any case, usually there is an approval process. So, does it look good? Does it need a little bit more work? And it's okay if it does need more work and it doesn't get approved immediately. You just need to go back, answer more questions, revise things. And then potentially get it re-reviewed. Or sometimes you might also get a conditional approval. Or you might also get a lot of valuable feedback. In that case, you want to revise your tech spec just so that everyone is on the same page. And then you want to start building.
Which is always fun.
And throughout this process, there are ways to set up your engineers for success as well. So, what I suggest is identifying the minimum requirements that you want to see in your team's tech specs. So, what content do you expect to see there? And you can take this a step further and translate those requirements into a shared template. And I think sharing it as a template is really valuable. Because it saves people cognitive load about what to actually put in it. And it's already formatted so they don't have to worry about spending time to make it pretty. You're just trying to get them to focus on the things that they are good at. Or the skill that they are trying to develop, which is planning.
And another thing that I really suggest is organizing your team's docs in a place where it's easy to find. That way people can get feedback in a more effective way. Or people can find the things that they need to give feedback on. And it also gives a way for engineers to look at previous work and to understand what happened in the past. Or like why something was done a certain way. So, it's sort of like an archive. You should make it easier to find. And you should be sharing real examples of tech specs with newer engineers whether they're new to your company or whether they're new to engineering in general. I think it's valuable information. And to include them in reviews so that they know what to expect. And so that they can sort of figure out what to do when they have to go through the process and to see how things happen from beginning to like the end of a development cycle.
So, I just shared a ton of information. But to sort of sum up everything, I made a sample template that you can share with your team. You can modify. Whatever you want. Have at it. It is available at Linna.la/techspec. But that is all I have for today. Thank you so much for listening to my talk. And go have fun, make some friends and build some cool stuff! Thank you!