Learning how to effectively write a project proposal or technical design is an incredibly important element of a software engineer's skillset. It's the primary way to communicate what you'll be working on and why it matters to a wider audience. The resulting documents serve as an invaluable resource when trying to understand any large engineering codebase or product.

Unfortunately, this skill isn't well taught- like so many other "soft" or less technical skills, learning to write well isn't prioritized at the same level as learning traditional engineering practices. From personal experience, it's a skill learned through trial and error, reading a LOT of designs, getting a tremendous amount of feedback, and building off of designs written by others.

Because of that, I hope to share my learnings and approach to writing project proposals. There are a lot of great blog posts out there about other engineer’s approaches to documentation and project proposals- I highly recommend searching for them and utilizing them as well. I’ve also linked some of my favorites in this article.

For reference, I will be using the term project proposal to also encompass technical designs and tech specs- these are any piece of documentation used to convey a problem to be solved, its solution, any potential costs associated with the solution.

First things first - get in the right state of mind

Alone we can do so little, together we can do so much

I want to firmly echo sentiments shared in this blog post- having the correct state of mind regarding project proposals is, in my opinion, the most important part of writing an effective document.

Project proposals are not meant to only be used for future reference or decision documents- instead, they should be also be seen as a tool to help hone your design and approach to a problem. They are meant to be living documents up until the point that reviews are done. They should be seen as opportunities for collaboration. By treating your project proposals as collaborative documents, you are able to get a wide variety of opinions and backgrounds weighing in on your solution. I’ve had many occasions where an idea I suggested was not the best approach to something and a better alternative was suggested by a collaborator.

As an added bonus: getting less experienced engineers to collaborate on a document can often help them gain exposure to new ideas and experiences that will help them mature into more senior engineers. It also has the benefit of introducing a less biased viewpoint into the review process. These more junior engineers often times have not been subject to the “right way of doing things” and come up with fantastic new approaches to solving problems.

What is and what is not a project proposal:

Just as it is important to remember that a project proposal is meant to be a living document, it’s important to keep in mind what the end goal of it should be.

A project proposal or technical design should:

• Be easy to understand for less-technical audiences.

• Clearly explain what problem is trying to be solved

• Be vague in places (prescriptive not descriptive)

• Focus on longer term solutions (if possible)

• Consider other viewpoints or solutions

A project proposal or technical design should not:

• Focus on more than the problem at hand

• Be perfect

• Be written in one day

Digging in a bit deeper on these concepts...

Keeping it high level and setting the correct context

While other engineers make up the bulk of your intended audience, it’s important to remember that project managers, people managers, business folk, stakeholders, etc. will also be looking at the document. Try to keep from diving too deeply into how something will be implemented or technical details. It's important to bear in mind you should ensure you explain what you're solving for before you even start talking about a solution. It's always best practice to assume folks are not coming in with the context you might have regarding the project.

Project proposals should not necessarily draw out the nitty-gritty details of how to solve something- it should take a ten thousand foot view of the problem and implementation. Because of that, if there’s something you don’t know the details on how to solve, acknowledge that this will be worked out later, propose a rough idea on how you might solve it, and move on. While it's not always possible, it’s important to try and consider the long term implications of your solution (this blog post by Chuck Groom lays this concept out nicely).

What resources are available to you? And what is the actual problem?

It is important to note, that while longer term solutions are obviously the ideal, they’re not always possible given constraints. There will be times where you need to design a placeholder, something that you know will be rewritten later when there are more resources available. If this is the situation you find yourself in, that’s okay. Try to incorporate what you think the next solution might be in your design, but recognize sometimes you need a solution now.

As important as it is to define how you will solve a problem, it’s also important to call out how you will not solve a problem. You should note approaches you considered but opted not to take and why. By including the solutions you chose not to take, you articulate alternatives and why they were not the best option. See “Why Write ADRs”- ADRs are not the same as the project proposals, but require a very similar mentality. Keep the scope of your document limited to only the problem you have been tasked with solving- don’t try and solve every issue your team needs to work on in one document.

Don't rush it

As mentioned above, project proposals are intended to go through many drafts and revisions. At first review, your project proposal should be easy to read without grammatical errors, but doesn’t have to be perfect. Give yourself space to iterate on the document; rushing through it will result in a final product with holes that can lead to issues down the line.

Writing the darn thing

Choosing the right tools

Because project proposals are meant to be collaborative documents, I would highly suggest writing them in a platform that encourages collaboration, such as Google docs or Confluence. I personally prefer writing a rough draft and soliciting initial feedback in Google docs, as it is less public of a platform (my designs are generally a brain dump on first iteration…). Later iterations and the final proposal are shared via Confluence.

If you have the luxury of being in an office with other engineers, I would suggest booking a conference room and doing a brainstorm session with a whiteboard. I recommend to have a rough proposal of a solution and clear description of the problem at hand ready to discuss. This proposal can and should be ideated upon, but it is helpful (and respectful of others in the room) to go into these meetings with a starting point.

How to structure your proposal

Generally, I break my project proposals into 3 major sections:

1. Background information

2. The actual solution to the problem

3. Outstanding questions, testing and monitoring approaches, and next steps

Setting the scene for your audience

What are you solving for? (i.e. background information)

Before you actually get into writing a solution, you need to articulate why there’s a problem that needs to be solved. This section will provide background on the product, the pain points you’re trying to solve for, and set any required context so readers understand why the document exists. This section is a great place to highlight existing solutions or workarounds if they exist, and why they are no longer appropriate.

The background information area is also a great place to define commonly used terminology or phrases you’ll be using in your document.

Lay out the requirements

This area is useful for highlighting the constraints you’re working under, as well as the expected minimum requirements for any solution. Requirements can be provided by your project manager or stakeholders, and can incorporate current technological limitations.

Your requirements may change as you speak with whoever asked you to write the document- it’s totally okay for a back-and-forth to happen as you get more clearly articulated requirements. The goal of this section is to have a list of clearly achievable goals your project has to solve for and to guide you in making decisions about your final approach to the problem.

Before you come up with any solution, you need to ensure you’re considering why a solution needs to exist and ensure your solution is solving the right problems. NerdWallet has a fantastic mentality I’ll call out here- drivers before solutions.

Assumptions

This section is a bit shorter and not always necessary, but it’s a good place to again get everyone on the same page. Assumptions in my opinion should be a section that highlights the assumed environment your solution will live in.

Digging into your solution

Breaking it down

This should be the largest section of a project proposal where you’ll dive into the meat of how you’ll solve the problem. It should be broken up by the individual components of your solution. It’s a fantastic place to include high level architectural diagrams or links to external resources and existing processes.

It might be tempting to get very detailed in this section. Resist this temptation. A project proposal is not the place to implement your solution. Instead, it should give a rough outline of how you plan to tackle a problem, the different pieces that go into solving that problem, and a high level overview of how they all work together.

Resources or technologies required

This is again a shorter section that complements the solution you describe above. Here, you outline which technologies or resources you’ll need to achieve the solution, as well as the reasons for choosing them.

what are other people doing?

Remember the note about architectural decision documents from earlier? This is where those concepts come into play. As important as it is to say what you plan on doing and why, it’s equally important to document what you’re not going to do and why you’re not going to do it.

This is a section where you can document alternative ideas you’ve come up with, third party solutions, or ideas that you got from others in the industry. The research that goes into this section can sometimes help you find a third-party solution that already exists for your problem. There’s a phrase, “sometimes it’s better to buy than build”- explore your options, and state why you’ll not be pursuing some of them here.

Wrapping it all up

Testing and monitoring

This is unfortunately a section that is often forgotten, but is incredibly important. Here, you should highlight if your solution will have automated testing, user testing, etc. How will you know if your solution works correctly? Similarly, how will you monitor the state of your solution? Datadog dashboards? Logging mechanisms?

Be aware of risks

This is a section where you call out the worst case scenarios you might encounter. What can possibly go wrong with your solution? Where might it be brittle and break? Your design might not have any apparent risks, and that’s okay- by thinking through where things can go wrong, you can oftentimes prevent errors from ever occurring.

The thing everyone forgets: Maintenance and change management

This is largely an optional section, but it is worth thinking about. How will you maintain the code or technologies that encompass your solution? How will changes here be shipped?

Open questions/FAQ

This section is intended to capture any questions you don’t have an answer to and to highlight areas you were a bit hand-wavey about earlier in the document.

By including a section with open questions, you can help identify potential risks to the project plan, but also provide reviewers items to think about. They may even come back with a solution you can incorporate into your document. Having an FAQ or section with already answered questions saves you the future work of answering questions from reviewers.

Next Steps

After receiving review and (hopefully) final sign-off, work with your team and your PM to break up your project into smaller chunks of work. This phase is also where you can dive deeper into implementation details. Make sure to store the proposal in a location with your teams documentation. It is intended to remain a public document, used both as a guide as your project it is implemented and an artifact for future reference.

Quick tips on writing a proposal:

• Take your time. As I mentioned before, it’s okay if it takes you awhile to write a project proposal. I generally will write a large number of notes and a rough outline before I dive deep into writing each section of a proposal, and will often jump back and forth between sections.

• Read it aloud. Your brain is actually cool in that it will try to autocorrect what what you’re reading, so you don’t notice small grammatical mistakes or misplaced words. While this is great when you’re reading a novel for for pleasure, it’s not great when you’re preparing a technical document for use by others. Reading the document out loud before others review it can be a bit tedious, but it’s a great way to capture errors. (Did you spot the double word in this paragraph? That’s what I’m talking about).

• Use others. There is a great deal of fantastic resources out there about how to write technical documentation. Take inspiration from others who have done things well (or not so well) in the past.

• Use a style guide and watch out for passive voice. This is a really tricky one, especially if you’re like me. There are a ton of great technical style guides on this page, and this is a particularly good guide in how to find places where you use a passive voice. TLDR: Be on the lookout for be (was, am, are, been, is) in your sentences.

• Pick up a book/magazine/newspaper. This might be my own personal bias in hobbies shining through, but I’ve found the more I read, even for pleasure, the better I become at communicating my ideas and writing coherently.

Closing thoughts