00:00:05.420
Hi, my name is Michele Titolo, and today I'm going to be talking about writing design documents for wide audiences. I'm currently a software engineer at Square, and I fully admit that before I joined Square, I had never written or read a design document before. So today, I'm going to share with you the things that I've learned that have helped me get really effective at writing design docs.
00:00:22.500
To begin, I'm going to provide an introduction to design documents. If you've never heard of design docs or have heard of them but haven't used them before, this will be a great introduction. If you have used design docs, but maybe it was a while ago or you are looking for some extra information about them, we'll cover that as well.
00:00:40.980
So, what is a design doc? When I say design doc, I mean an engineering design document. This is a technical written document that details what you plan on building. Note the word 'plan,' because design docs are future-looking. They're not something you write after you've completed your project, and they're not something you write while you're currently building.
00:01:05.339
Generally, design docs have a set of sections that you'll use or a template if you're starting from scratch. Don't worry; I have some suggestions for these later. Now, what is the purpose of writing a design doc? Why would you want to use one?
00:01:29.159
Firstly, design docs are a fantastic communication tool. They provide a place to write all of the information about what you want to build down, ensuring that it's accessible to others. This also makes design docs a wonderful collaboration tool because by writing everything down, other people can read it and provide feedback, ask questions, and seek clarification—essentially all the great stuff that helps build alignment on what you're building.
00:01:55.380
Some organizations require explicit sign-off on design documents, but I find that this isn't necessarily a good goal or purpose. You don't want someone to just rubber-stamp your design doc; you want rich, meaningful feedback. So the real purpose is building alignment, not just getting approval.
00:02:19.500
My favorite purpose of design docs is fairness. If you enjoy checklists, you will love design docs because they force you to consider various aspects of what you want to build.
00:02:32.760
Now, what are the benefits of doing a design doc? This ties into the question of why you would use one. Since they are great collaboration and communication tools, socializing your designs is a fantastic benefit of design docs. This not only helps gather feedback but also helps other people understand what you're building.
00:02:52.379
It allows you to leverage the experience of others. For example, if someone else has run into a problem similar to what you've designed, or if someone is excited about it and wants to propose new features, this helps you gather that feedback and incorporate it into your design before you actually sit down to build.
00:03:18.000
Lastly, this process helps reduce surprises. As engineers, we work in very complex systems, and while we can't fully eliminate surprises, having sections or templates helps you navigate through checklists. Additionally, utilizing the experiences and perspectives of others can greatly reduce the number of surprises you'll encounter as you move forward with your project.
00:03:39.659
If you're in an organization that is product-focused, you might be used to working with Product Requirements Documents (PRDs). These relate to engineering design documents but are not the same. Generally, design docs will reference PRDs; that's where the design docs get their requirements from.
00:04:03.060
At the end of the day, these are very similar documents, but they have different purposes. PRDs define why certain features need to be built; what is the business case? Engineering design documents are for planning and serve as a technical document.
00:04:30.600
When should you write a design document? If you're trying to figure out if a particular project is a good fit for a design document, consider projects that have non-obvious or new components. This generally leads to more exploration work or just more unknowns. Additionally, any project that is significantly cross-team or cross-functional is another excellent opportunity to use a design document.
00:05:04.620
Design documents are planning tools, so you generally write one during some planning phase or some intermediary phase between the official plan and actually sitting down to write the code. This is because design documents help break down different parts of the project, leading to better estimates and ultimately a better outcome.
00:05:32.160
You're probably wondering, okay, if I'm not supposed to write the design document while I'm building my project, how do I figure out what I need to build? This is where prototyping or proof of concept comes into play. Prototyping is generally done before or during a design document, helping you figure out all the things you are unsure about.
00:06:10.620
It's completely reasonable to work on your design document and discover that you don't know how something functions; at that point, go prototype, and then come back with the solution. In doing so, prototypes help inform your design to be more realistic by transforming unknown unknowns into known unknowns.
00:06:33.539
You may not have all the code ready, but you will have a general idea of how you're going to solve that problem. When you're prototyping, I suggest time-boxing or constraining the prototype in some manner, such as focusing on a specific set of features or solving a particular problem.
00:06:50.829
If you are someone who likes taking extensive notes during prototyping, be sure to link those notes in your design document. Other thorough individuals will appreciate having that context.
00:07:11.940
Now, let’s discuss where you should write your design document. If you have a collaborative editor, I highly recommend using that for your design docs. Options like Google Docs, Notion, Dropbox Paper, or even Office 365 have the capabilities to facilitate collaboration. The reason for this is that you want everyone to have a single source of truth for your document.
00:07:55.860
You can absolutely write something locally on your machine and share it through email or file shares. However, this leads to multiple versions of the file being created, making it difficult to track comments and different copies. With an online version, everyone has a single location to look for updates.
00:08:17.760
This also helps with versioning; you simply use the most recent version available online. Additionally, it serves as a centralized location for discussion. If you have a meeting or a call regarding your document, you can easily add comments referencing your discussions for clarity.
00:08:41.940
Now that we've gone through an introduction to design docs, I want to cover how you actually write one. First, figure out who your audience is. This is incredibly important to do early because it informs what goes into your design document later.
00:09:06.560
I generally categorize audiences into three types. The first is a vertical audience, which might include your reporting or management chain—people who may not necessarily be individual contributors at the company reading your document. The second type is the horizontal audience, which includes other individual contributors, such as engineers.
00:09:32.880
Regardless of your work, most projects will have a horizontal audience since your team is typically interested in what you're building. Lastly, there’s the combined audience—this is more common for larger projects, where you might have significant aspects of both vertical and horizontal audiences.
00:09:55.980
If you're unsure of who your audience is, I’ve put together a few questions to help you research and determine who that audience might be. First, consider who will be impacted by the project once it's built, released, and in production. Who'll integrate with this? This is especially important when dealing with interactions between an API and a front end or a mobile application.
00:10:53.100
Next, consider who will ultimately use this. Even if you're designing a front-end component intended for customers, it’s essential to recognize the roles of customer support in the process. They may need a new knowledge base article about how to use this feature, or their internal protocols may need updating. Finally, identify any other stakeholders you regularly collaborate with that may care about this feature. This can include areas like security compliance or finance.
00:11:30.360
Next, let’s talk about the sections of your design doc—every section matters, so you'll want to be purposeful in what you include. People generally read these documents from top to bottom, so if you have details you want to expand upon later, consider moving them earlier in the document.
00:12:00.300
Defining your sections can be a challenging process because there are numerous options. I’ve worked hard to create the smallest possible list of expected sections for a design document. The first section is the reviewers, which includes individuals whose feedback you want to cultivate. Some organizations may require formal sign-off as well. Next is the audience section we just discussed.
00:12:44.300
Following that is the background section, where you will include context to help readers understand the project. It's followed by the goal and non-goal sections and then the architecture and design section. These three sections will need more explanation, which I'll cover in greater detail shortly.
00:13:34.500
Before I dive into those, let’s revisit PRDs. If you don't have a PRD, ensure to include the requirements you're working from in a designated section of your document and circulate that early on in the process. You don’t want to discuss project requirements in conjunction with design alignment, as that will lead to unnecessary back and forth.
00:13:59.700
So start off with your requirements if you don’t already have them. Now about the background section—the wider or larger your audience, the more important this section is.
00:14:13.340
If your audience comprises teams that already have context, you can shorten this section, but it should still provide enough information for everyone to get up to speed. It's also an ideal place to discuss any additional context that may not be obvious.
00:14:39.780
You’ll want to address any constraints or challenges that could arise during your design choices. The goals and non-goals section may have raised some eyebrows earlier, but it's crucial for explicitly setting the scope of your document. We've all encountered projects with scope creep, and you certainly don't want your design document to drift into the same issues.
00:15:06.480
Use the goals and non-goals liberally. This section is also a great place to lay out specific use cases and non-use cases. For instance, if you're building an internal tool for developers, perhaps it will initially be released as a command-line tool. This would be a goal, but building a user interface might be labeled as a non-goal, which is important to identify.
00:15:29.760
Thanks to specifying non-goals, you can keep other reviewers focused on what you want to be addressed in the document.
00:15:55.380
Then, we have the architecture section, which is the most vital and often the longest part of your document. This section is where you describe what you plan to build, which may sound simple, but it can become quite complex.
00:16:17.660
Choosing the right level of detail suitable for your audience is essential, as well as for the size of the project. It's quite common for larger projects to have multiple design documents: a high-level overview followed by more detailed documents that elaborate on complex system components.
00:16:38.740
You’ll also want to leave room for surprises. Don’t delve too deeply into areas you aren’t sure about, because sometimes the details won’t be fully fleshed out until you start working on them.
00:17:02.579
Additionally, don't forget to discuss trade-offs in this section. If you're building a system with strict latency requirements, mention how that relates to the caching mechanisms you'll be using. Conversely, if you're developing an offline system, you don’t need to worry about optimizing database queries.
00:17:29.760
I want to mention API contracts specifically, as they are a great topic to address with reviewers and some people in your audience regarding how the API contract will work. Be sure to include this, but don't go into too much detail about implementation code.
00:17:51.840
In documents discussing SDKs, frameworks, or libraries, some code will appear as you discuss. However, avoid getting into the specifics of how different methods or functions will operate. Remember, a design document is not a pull request and not a substitute for code review.
00:18:10.980
When it comes to diagrams, we have all seen poorly put together visuals. If there’s one thing you should remember about using visuals or diagrams in your design doc, it is this: every visual should serve a single purpose.
00:18:41.760
Avoid cramming too much information into one diagram—this means separating out every concern you want to illustrate into its own visual. While your document might end up with five, six, or seven diagrams, clarity is worth it. Make sure you describe each diagram within the document; don't simply add images without any explanation.
00:19:05.200
Different people learn in various ways, so while some may understand your diagram without additional text, others may not. Thus, ensure your document remains easy for everyone to understand.
00:19:37.560
If you include any numbering or lettering in your diagrams, copy it out and use that as text in your descriptions. Since most diagrams are in picture format, issues arise when trying to comment on specific parts, often resulting in confusion.
00:20:01.380
To avoid this confusion, ensure conversations about diagram steps can be organized separately through comments related to specific steps.
00:20:21.360
While I just covered the minimum required sections for a design document, you can certainly add more sections depending on the size of your organization and the kinds of work you do.
00:20:45.820
Some additional sections to consider are security, compliance—especially relevant for GDPR and CCPA—customer privacy, cloud costs, and the costs associated with running the service. It's also beneficial to outline monitoring and alerting service level objectives, service level agreement details, and to prepare a disaster recovery plan as things will inevitably go wrong.
00:21:16.000
Lastly, remember that engineering design docs are planning documents, so including estimates or a breakdown of milestones or epics helps others understand how parts of the project can be worked on either sequentially or in parallel.
00:21:47.180
Finally, I want to discuss how to build a design culture at your company. Writing a single design document is a great first step, but the benefits become much more significant as this practice integrates into your cultural norms.
00:22:07.260
To get started, begin small—not only with the projects you're working on but also with the size of the design documents. If someone’s first experience with a design document is a 30-page long document, they may feel intimidated and reluctant to engage in the process.
00:22:48.300
Encourage buy-in from potential reviewers before working too hard on your design document. You don't want people questioning why you're writing a design document while you're trying to get them to agree to what you’re proposing, as this can derail efforts.
00:23:18.159
Typically, you would circulate design documents for review before sharing them more broadly. If you start with just your close-knit team or team you work with regularly, this can help lessen the feedback you receive from other teams as they see your close colleagues have already provided input.
00:23:55.980
Additionally, if you have existing meetings that discuss architectural decisions or planning, incorporate the design document into that meeting or schedule a separate design review meeting. This solidifies it as part of your established processes, making it easier for teams to adopt.
00:24:34.560
However, keep in mind that establishing a design doc culture will take time, as it requires a cultural norm to take root. Ensure everyone involved sees the document's value.
00:25:24.560
Shifting gears, let's tackle the elephant in the room: design documents are written—they're merely words on a page. This fact makes strong communication skills essential for how effectively your design docs will be received.
00:25:55.360
The great news is that writing is a skill that can be improved over time. Just as you become more proficient at writing design documents, your writing overall will develop too. I'm going to share some helpful resources for improving your writing.
00:26:34.920
For those unfamiliar with writing long documents, you might find these resources invaluable. The first is a classic book titled 'The Elements of Style' by Strunk and White. Though it may be dated, it's a useful reference for common mistakes and writing pitfalls. It's a cheap investment and worth having around for occasional reference.
00:27:13.740
Another great resource is the Google Developers technical writing courses. These are available online for free and cover many fundamental writing skills in a manner that's relevant to technical writers. Their examples often relate to familiar concepts, such as databases, and I found it useful for those not versed in technical writing.
00:27:51.420
As you work on writing down your plans and circulating them, you might be worried about the potential for bike-shedding or your design doc becoming sidetracked by undesired discussions.
00:28:37.239
Unfortunately, sensitive or controversial topics may not always be avoided in design docs, so it's crucial to develop strategies to minimize the impact of these discussions. Consider that a design doc is not a manifesto. It isn’t the place to philosophize about past actions.
00:29:15.600
Instead, it's essential to communicate constructively without passing judgment. Non-goals should be employed liberally throughout the document to set boundaries. Hedging statements or setting these boundaries can foster a respectful dialogue around your work.
00:29:47.880
When addressing concerns, grounding your points with factual, concrete implications will help facilitate more constructive conversations. This ensures the focus remains on the document itself.
00:30:12.000
As an example, consider the contentious topic of monoliths. Instead of stating that ‘the monolith does not scale,’ a more constructive statement would be, ‘in order to serve X requests per second, the monolith needs to scale to Y nodes, which could cause issues with the database limited to Z concurrent connections.’
00:30:42.600
This rephrasing maintains the original sentiment while emphasizing the specifics of the design challenge, fostering constructive dialogue around the concerns as opposed to making judgments.
00:31:12.159
To summarize, aim to write your design document in ways that promote alignment. If it's too judgmental or negative, readers won't respond well. A welcoming and informative tone fosters a better understanding of what you're building.
00:31:39.480
Lastly, be aware of common pitfalls you may encounter while learning to write and utilize design docs. First and foremost, design docs are not end-user documentation. They may contain valuable information about the system you're building, but they should not be confused with instructions for how to use it.
00:32:00.600
Also, design docs aren’t permanent documents. Commonly, organizations do not revisit or update them once initial iterations complete. Therefore, appreciate the time commitment needed to write them.
00:32:18.680
And while some may argue that thorough upfront design helps to reduce scope creep and surprises throughout your project, start smaller. You can begin with a one or two-page document to ignite conversations.
00:32:47.080
You may occasionally encounter those who feel they don't have time to complete a design document. Sometimes, they are correct—if things are actively crashing, it's not always the best time to plan.
00:33:09.200
However, others may have misconceptions regarding the importance and benefits of design documents. In those cases, collaborate with your team to establish cultural norms and engage in constructive conversations about why design documents should be valued.
00:33:34.160
That concludes my talk! I hope you leave here with a greater understanding of the significance of design documents!
00:33:54.520
Effective design docs steadily work towards their goals, allowing the document to build upon itself while focusing the reviewers on its details without distractions. With time and practice, you can hone your design documentation skills and ultimately improve your impact and reputation within your organization.
00:34:17.400
Thank you!