Software Projects Planning/Design Template

This is a template I use with my team/s to help us plan/design medium to large software projects. The team/s work together to fill some or all of the parts between {}.

The main goal of this template is to work with your team/s to design/plan one ore more solutions for a new project after you did pre-planning/analysis to define the problem you are trying to solve.

{OKR/Project Name}

Team Members

{Engineers work on this project}

Purpose

{This Document can be used to help engineers to work together in planning and designing solution/s to the problem/s we need to solve with OKR/s, they can break down OKR/s into smaller self-included/independent pieces/sub-problems and design solutions to each piece then integrate all of them together to achieve the overall goals of the OKR/s, It help engineers think in a concrete way about one or more solutions to each sub-problems, measure and communicate tradeoffs and take a thoughtful decision/s about the solution/s they will move forward with.}

Goals

1. {Clearly Define the OKR and include {pre-planning doc}}

2. {Break down OKR into smaller pieces/sub-problem if possible- make sure they are self-included and one or more engineers can work on it independently}

3. {define dependencies between pieces/sub-problems to help priorities them}

4. {Design one or more solutions to each sub-problem and make sure the solution can integrate easily with other parts of the system }

5. Create ADR for the solutions and include tradeoffs you are making

6. Communicate with leaders (e.g Architecture guild) and/or team members to review your solution/s and ADR/s

7. Create a sprint by sprint estimation for your solution implementation (high level, does not need to be 100% accurate)

8. Quickly think about what could go wrong about your plan and how you could get around this. (again just 30 minute is enough for this)

9. Think about a roll out/integration plan for your solution/s with the rest of systems integrating with it.

10. {Stakeholders, (teams , leaders and managers we need to work with)}

11. {Define the end state of the system/s (code, Data Flow, Infrastructure, Integrations , Testing, Monitoring, Dependencies) after your solution go in production}

Design/Planning

{Go deeper in each goal to gather more information}

{OKR definition}

{e.g, Build new data pipeline in a new environment.}

OKR break down

You can breakdown OKR in different ways (make sure the work can be done in parallel with other pieces/sub-problems):

A. Break down based on logical and physical structure, e.g {code changes, infrastructure changes and integration changes}

B. Break down based on system logical entity e.g {service layer, infrastructure, code and integrations with DB}

C. etc..

Define dependencies between sub-problems

A. Define which sub-problem dependencies are in two-ways and which is one way dependency

B. Based on dependencies define which sub-problems need to go first and which can be done in parallel (e.g problem A need to be done first or it will block others)

Design one or more solutions to each sub-problem- ADR

A simple way to think about you solution is to define whether you can go from the current state of the system to the desired state in one step or not, if you think the solution need to be implemented/deployed in stages/multiple-steps this is okay just make this clear in your solution, in a lot of cases though you already broken down the OKR into a smaller sub-problem that can be solved in one implementation/deployment.

A. Create an ADR for your solution that should include the following

1. The problem statement from pre-planning

2. Clearly define your approach for each solution make sure you include the following

a) Enough details about the way your solution could be implemented

b) Explain use case/s and how the data will flow end to end in your solution

c) Write down any new API and/or API changes

d) Write down any suggested data model/schema changes

e) If there any scaling concerns or solutions explain them and write how your solution

address/fix them, specially any expected bottlenecks in the system/solution

f) Where the changes could be made, code, infrastructure, configs, extra logs and monitoring, etc

g) How you will test your solution.

h) How you will rollout your solution

i) High level diagram for each solution

(1) Include all components for the solution whether it is infra , code or integration

j) Low level diagram for each solution - Optional

(1) If high level diagram is not enough create a detailed low level diagram

k) Pros and cons of each solution

(1) Make sure you define tradeoffs between solutions and what make a solution your

first choice

(2) Think about different aspect of the solution e.g some solution could be easy to

code but hard to rollout or integrate , some could require more integration or

testing more than others and a lot of them could have performance or reliability

downsides

(3) Keep it simple , think about the simplest solution first, the one that require less

testing and integrations even if it is not the best solution or the best performance after that you can iterate and improve on these areas

l) Finally select the solution you decided to move forward with

Ask for ADR review and feedback

A. Now is a good time to review your ADR, this can be done within the team , ASK Architecture Guild or invite multiple engineers to review it

B. Make sure you ready to answer some questions about your solutions

C. Take notes and make sure you have a closure in your meeting where you clearly define which solution you are going to implement

D. Make sure you make updates to your ADR after review to reflect the solution you will implement

Create a sprint by sprint breakdown estimation for your solution

A. Make sure you follow dependencies , priorities and define tasks need to go first, also define tasks can go in parallel and create your sprints based on the resources dedicated to the project

Think about what could go wrong

You probably had some thoughts about that when you were thinking about pros and cons of your solution but it is worth thinking about possible blockers and/or hiccups one more time, maybe you could take precautions or extra steps/testing to avoid it.

Roll out/integration plan

A. Make sure you think about how you will deploy your changes, this step is also part of the sprint by sprint breakdown estimation, because some parts of your solution could go to production early on

B. Make sure you define necessary config updates or infra updates needed as part of your deployment

C. Make sure you communicate your deployment to any team/s integrating with you.

D. etc..

Stakeholders

{Define stakeholders early on, eg Org A, Team B, Product Manager etc.. }

System/s state After deploying OKR solution:

{How your systems will look like after the project finish}

A. Code {list all modules, libraries involved}

B. Data flow {list use cases for data flow inside the system}

C. Infrastructure {list all infra involved, regions, ec2s, msk, ES, S3 ,etc}

Draw one or more diagrams of infrastructure, try to have high level and low level diagrams after the change

D. Integrations {list all systems , infras we integrate with now} - optional

E. Testing {list all unit test, Itest, performance and testing required for code and infra } - optional

F. Monitoring {list all available alerts, dashboards}