Subscribe to access the entire course.
🌶️ tip: unsubscribe at any time.
Ah, that's a great question!
Frontend at Scale is a bi-weekly newsletter (as in, once every two weeks) that is all about software design and architecture for frontend engineers.
Subscribing to the newsletter is the best way to support my work and encourage me to keep making free resources like this one.
I probably don't need to say this, but I would never ever spam you—and you can unsubscribe with a single click at any time.
Already subscribed? Don't worry, you won't get double-subscribed. Nobody deserves to read my terrible jokes twice.
Module 3: Designing
[00:03] We’re going to finish this module by talking a little bit about design docs. This docs are sort of like informal documents where we describe our solution to a problem in some level of detail, and then we can share those documents with different stakeholders or with our team and get feedback on a solution. There are essentially two levels of detail of these docs. There are the high level design docs on the low level design docs. They’re very similar in terms of structure, but high level design docs are more appropriate when you want to describe an entire architecture or something that requires more, more context and low level design docs are great when you’re trying to describe how you will implement a particular feature in these type of documents.
[00:46] You might include pseudocode or you might include mock APIs or mock data types and so on. The company that you work at probably already has some sort of template or structure that they like to use for your design documents. But if you don’t have one, I can recommend one that it’s pretty simple. It has a number of different sections, but it’s still a pretty simple structure for our design doc, and the main sections are an overview. We’ll start by in no more than one or two paragraphs describing what the document is about.
[01:18] Our context section. When we explain everything in every context that is necessary to understand document and this section may include any system context diagrams like the ones that we saw in the previous module. The goals and non-goals of the solution. So this will describe what things are in and out of scope for this particular problem. A high level design, which in the case of an architecture, we can include our container diagram. We can also include, we can also describe the architecture using the four dimensions of architecture that we saw in the previous video and any alternatives that we might have considered while putting together this design.
[01:55] So these may include any frameworks or libraries or technologies that you decided not to go with and why you didn’t go with them. A section describing the detailed design, which is typically only in low level design documents, and this is where we may include a pseudocode and maybe some low level diagrams, a timeline that will include how long you think the project will take or how long it will take to implement this design. And of course, the larger the project, the the harder it is going to be to estimate it. But at least we should include our best guess, any risks and open questions that we may have and on appendix, including links to other relevant documents as well.
[02:37] So here we have an example of a high level design document that I put together for FullSnack. We have a brief overview of the problem. We have some context. We, including the system context diagram that we saw earlier, the goals and non-goals of the system, the high level design, which describes the architecture at a high level. So here we see the container diagram that we we draw earlier. This is a more polished version of the container diagram, and we also describe the architectural style of our application and saw the key components which are the modules.
[03:11] So this is how we’re going to break down the application into different modules, The technology stacks, including some of the decisions that we made. And then we see the alternatives that we consider any other frameworks that we might have considered for this project and why we didn’t choose to go with those options. The timeline includes, again, the best guess of how we can implement these models. Given our constraint of four months, you might you might say that this is an optimistic timeline, but it is what we have and these are fictitious projects so we can dream a little bit and then some risks and open questions.
[03:47] And finally, the appendix that plays to to some of the other documents that we talked about earlier in the course, like our requirements document the domain model and the idea that we worked on The last piece of advice that I have when it comes to writing design docs is to keep them as short as possible. It may be tempting, especially when we are working on these large projects, to try to include as much information as we can in the documents.
[04:12] But this will first of all take up massive amount of time and second, it will reduce the chances that people will actually read them. And we want people to read them because we want to get feedback on them. That’s one of the main reasons why we write the doc in the first place and that’s it.
[04:28] We’ve reached the end of module three. Now we’re going to grab this is design document and we’re going to use it as an initial plan for the implementation of the project, which is what we’re going to see in the next module of the course.