How to Create a High-Level Design Document

Every good software engineer knows that you need to have a design for your software before you start building it. You may be able to get away with just an interface design and a few lines of comments describing your code for smaller programs, but it’s not feasible with larger programs. For example, the small programs we’ve gone through in the Super Simple Python series don’t need a design, but larger ones do. There is no way I would have been able to even attempt creating The Text API without some sort of design.

After graduating from college, I started working at Amazon as a Software Development Engineer. That was where I was first introduced to the concept of design documents. At first I was like, what the hell is this? I don’t need a design document, I know how to code. I tried to write my first program without a fully fledged design document. Boy, that was a failure. Ever since then, I’ve made use of design documents for anything bigger than a couple files. I would go as far as saying design documents are one of the most important parts of software engineering. So, how do we get started with these design documents?

High Level Design (HLD) for Software Engineering Questions

Thinking Image from Queen’s University

For a high-level design document we’ve got to ask the questions that will let us design our software for a purpose. No software is built in a vacuum. No software is built for no reason. Before we even get into the actual design portion, we’ve got to discover what we’re looking to build. Once we have our requirements down, it’s time to get into the design portion. When we’re designing how we’re going to build our software it’s best to break it down into three sections. First, we’ll build a functional map, then we’ll build out how we want to access the data, and finally we’ll determine the interfaces. A high level design doesn’t go as far as determining the interfaces, so for this post we’ll focus on the functionality and data. We’ll cover determining the interfaces in a future post. To learn more, you can read the book on the Blueprint for Building Software – Discover, Design, Deliver.

High Level Design for Functionality

One of the reasons it’s important to have a high level design doc is so that we can be clear about the expected functionality. It’s important that we know both what we’re starting with (if we’re adding a feature) and where we want to define the end of the project. With these in mind, let’s look at some of the high level questions about functionality we should be asking.

  • What features currently exist?
  • Which features will be considered in the scope of this project?
  • What are some discrete steps we can break the project into?
  • Which technologies are we using?
  • Which technologies are compatible with our end goal?

Of course, these aren’t the ONLY questions you should be asking, but this is a good start. Further considerations in functionality should be based on what you need your software to do. For more information check out the book.

High Level Design for Data Organization

Aside from functionality, another important consideration for high level design is how the data is organized. High level design includes determining where data enters the software and which modules interact. When considering data organization we have to consider where the data comes from, which modules have access to the data, and how the data will be stored. Here are some good questions to ask when designing the way data will be organized in your software. 

  • What kind of data will we need from the user?
  • What data will we need to store?
  • How will our data be passed from module to module?
  • Which modules need access to what data?
  • How does each module transform the data passed in?

Just like the questions for high level design on functionality, this is by no means a comprehensive list, but it’s a good place to start. Other considerations for what to do with the data will be based on your specific application and what you need it to do.

What Goes Into a High Level Design Document for Software?

blueprint
Blueprint Image from artit-k

You can think of a high level design document like a blueprint. The HLD is used to highlight a plan to build software just like a blueprint is used to highlight a plan to build a building. To make a high level design doc you’ll need to have the questions above answered and organized in a readable format. For example, let’s say I’m making a high level document for this post. It would look like the headers that I have chosen for this article.

In a high level design document for building software you need to a) outline the functionality, b) outline the data processes, and c) provide a diagram. Having a diagram is critical. If you’re building software that doesn’t require a visual diagram to understand, you’re either a) building something really simple, or b) not thinking about it the right way.t

What does a High Level Design Diagram Look Like?

The HLD below shows what a High Level Diagram for a simple API with users and payments would look like. I have left out some things for you to add in yourself like deleting users and updating user passwords.

high level design diagram example
Example High Level Design Diagram

Next, you’ll want to create a Low Level Design Document

Further Reading

Learn More

To learn more, feel free to reach out to me @yujian_tang on Twitter, connect with me on LinkedIn, and join our Discord. Remember to follow the blog to stay updated with cool Python projects and ways to level up your Software and Python skills! If you liked this article, please Tweet it, share it on LinkedIn, or tell your friends!

I run this site to help you and others like you find cool projects and practice software skills. If this is helpful for you and you enjoy your ad free site, please help fund this site by donating below! If you can’t donate right now, please think of us next time.

Yujian Tang
Yujian Tang

I started my professional software career interning for IBM in high school after winning ACSL two years in a row. I got into AI/ML in college where I published a first author paper to IEEE Big Data. After college I worked on the AutoML infrastructure at Amazon before leaving to work in startups. I believe I create the highest quality software content so that’s what I’m doing now. Drop a comment to let me know!

One-Time
Monthly
Yearly

Make a one-time donation

Make a monthly donation

Make a yearly donation

Choose an amount

$5.00
$15.00
$100.00
$5.00
$15.00
$100.00
$5.00
$15.00
$100.00

Or enter a custom amount

$

Your contribution is appreciated.

Your contribution is appreciated.

Your contribution is appreciated.

DonateDonate monthlyDonate yearly

4 thoughts on “How to Create a High-Level Design Document

Leave a Reply

%d bloggers like this: