Throughout our careers as software engineers, it's tempting to jump straight to coding when starting a new project. This works fine when projects are small and uncomplicated, but as complexity increases we quickly find ourselves forgetting details and making mistakes.
Preparing even a simple project plan before starting development can help minimise these mistakes and ultimately save you and your team a lot of time.
These project plans don't just help you keep the technical details straight, they provide enormous value by:
- engaging your stakeholders and ensuring they understand why this work is important
- holding you accountable to resolving concrete real-world problems (and not just delivering software without purpose)
- providing a way to discuss the project with other engineering teams
- benefit and learn from others' experience
As a general rule of thumb - any time your work is "architecturally significant" it's worth preparing a concrete plan before you start active development.
Imagine a basic service architecture diagram and ask yourself; "will this project change any of the lines on this diagram?" If the answer is yes, then you need a plan.
How to Plan
Resist the temptation to try and plan your entire project upfront. Instead build up your plan steadily through talking with your stakeholders, your team and any other impacted teams.
The process outlined below is a rough guide on how I typically build up a project plan over time:
- Start by describing the problem. Before you even begin thinking about possible solutions make sure you can clearly articulate what problem it is you are trying to solve.
Validate this problem statement with your stakeholders before moving into solution territory. If you can't agree on what problem you are trying to solve - then it doesn't matter what you build as it won't actually resolve your users pain. - Brainstorm 2-3 solutions with your team and jot them down in rough dot-points. These should be super high-level descriptions and not dive too far into the detail on any individual solution.
- Seek feedback on your solution ideas. This step is absolutely crucial and is really tempting to skip over. Before you spend huge amounts of time trying to write a perfect document spend some time sharing your ideas with anyone directly impacted by your project.
This might mean another team that maintains a service you will integrate with. Or potentially a Lead/Principal Engineer in your domain. If your company has a Solutions Architect make use of them!
The more people you get to challenge your ideas the stronger they will become. Throughout this process, you will find yourself coming to a firm decision on which solution works best. - Fill in the Details. Now that you have a reasonably concrete direction start filling in all the details on what you need to do. Stay reasonably high level and spend most of your time focused on the portions of your project which are the least well-understood or riskiest.
You may choose to simultaneously perform 'tech spikes' to help you investigate specific technologies/problems that your team has not encountered before.
You should continue to engage with your team and stakeholders as you go about developing this detail. - Seek Feedback again. At this point, you should have a solid project plan with a well-understood problem and a clearly defined solution. Validate the project plan as a whole with your stakeholders and any other interested parties.
Proactively ask for feedback on the portions of the plan where you are the least confident. - Get Started!
A few useful tips to keep in mind as you go about following the process above:
- Share early and share often! The more feedback you get the better your plan is going to be.
- Don't polish your plan too early! Keep the document as rough dot points for as long as possible. Ask your peers to focus on reviewing content and not grammar/sentence structure.
- Adjust the complexity of your plan based on the complexity of your problem and solution.
- Don't over-plan specifics. If you find yourself talking about class relationships or database table structures you are probably being too specific.
- Diagrams diagrams diagrams. A simple service dependency diagram can save you 1,000 words trying to describe the same thing.
Most importantly:
- Don't hide in a corner for weeks preparing a perfectly polished document. That just makes it hard to accept feedback.
Plan Format
The structure below is the format I use for almost all of my projects. You can find a standalone version of this as a Notion template here.
Projects don't always need all sections. Feel empowered to remove headings (or add new ones) if they aren't appropriate for your project.
Problem
What problem or circumstance necessitates this project? Articulate the problem you are trying to solve, not the solution.
The less you talk about software, the more you talk about your end-users, the closer you are to understanding the real underlying issue.
You might also find it useful to include the following:
- Success Criteria: A list of measurable outcomes you can use to ensure you have successfully solved the problem.
- DACI (Driver/Approver/Contributor/Informed): A short list of people who care about the project and need to be involved.
Proposal
The core of the project plan and where most of the detail will reside. Whilst in brainstorming mode this is where you should dot-point out your initial solution ideas.
Proposal - Overview
Briefly outline your preferred solution in broad detail. This should be a very high-level description of what the solution will involve.
Include a service-architecture diagram that shows what the architecture will look like once the project is complete. If your architecture is complicated it can also be useful to include a 'before' diagram as well.
Proposal - Custom Headings
Depending on the project this is the part that is likely to vary the widest. Any part of your project that is particularly complicated, risky, or involves new technology likely deserves its own section.
Essentially - any part of your overview that is likely to get lots of questions should get expanded in one of these.
Here are a few common examples that would likely deserve their own section:
- We will be integrating with an external API
- Why we need this specific new database technology
- How we will migrate data from Service X to Service Z
- How we will safely deploy this without downtime
- We are using a brand-new caching strategy
If your project has relatively clear 'phases' that need to be done in sequence you might choose to use this section to define explicit project milestones.
Proposal - Infrastructure
Outline any infrastructure you need to deploy or modify. This isn’t about providing exhaustive detail - it’s about ensuring you have thought about the impact of your change.
Will your project change traffic patterns? Does the reliability of preexisting infrastructure meet your needs? What about performance?
Proposal - Impacted Services
Describe any impact you are going to have on nearby services (or teams). Will you need to integrate with other services (internal or external)? Will this project require work from other teams?
Cost
Estimate any additional costs that this project may incur. In particular, consider the cost of any new infrastructure or changes to traffic patterns.
Wrap up
And that's pretty much it. Remember - the point of a project document like this isn't to write some perfect project plan that captures all possible scenarios.
It's about helping you engage with your stakeholders, collaborating with other engineers to define a broad solution structure, and identifying the genuinely hard parts of your project.
Check out this notion template for a standalone version of the format above.
