Introduction
It's so natural to want to start a new software project or story by writing code, as it's fun to write code! However, this approach can result in a lot of re-work, starting over from scratch, or making mistakes that could have been avoided.
I think planning is an under-utilized tool in software engineering. For me, it's my favorite productivity tip for any software-related work.
Planning means writing out the steps needed to complete a piece of work. I find it very powerful to think out all the steps necessary to complete a piece of work, as it makes you realize the full scope of what is likely needed to complete the work.
Planning applies to:
- a whole project
- a piece of work within a project (i.e. a story as part of an Agile process)
This blog post focuses on a whole project but can be easily applied to smaller pieces of work.
Benefits
Planning adds discipline to the software development process, as I hate getting into a state where I'm trying out different ideas and just feel like I'm spinning my wheels (working but not making progress). It can be really difficult to make progress when you don't have a clear list of tasks.
Once you have a plan in place, it's a great feeling to start checking off small tasks as completed. Seeing items checked off in your plan builds momentum to continue getting more work accomplished and it's easy to see that you're making progress. By creating a detailed plan of what needs to be accomplished, it sets you up with a higher chance to finish the project. It's so easy to start a project, but it's really difficult to FINISH a project.
The biggest benefit of planning for me is dealing with procrastination. When I'm procrastinating, I find it so much easier to work on a small task than to feel overwhelmed by a large concept to work on with little details thought out. It's easier to check off a single task on a to-do list, especially when you're struggling to even start.
Tools
Everyone has different approaches for creating to-do lists; I think you should use whatever tool makes planning easiest.
A piece of paper and a pencil are a great approach. A text file that lists out tasks is a great approach.
I enjoy using Bear for all of my note-taking and creating lists. I have a MacBook Pro and an iPhone, so the synchronization across these devices is a nice feature that I appreciate.
Markdown format is familiar to me and I like the visual representation of the Markdown in Bear:
Process
Writing out tasks feels like going through a project/story for the first time, then actually doing the work is the second pass through where you get even better clarity on what needs to be done.
My process of planning occurs in 4 steps:
Philosophy
Two of the most common software methodologies are Waterfall and Agile.
I've used both approaches and I try to utilize a hybrid approach.
The start of my planning approach is a Waterfall approach, as I come up with the major tasks for the whole project and plan out the detailed steps for the first few major tasks. After this initial phase, I shift to an Agile approach with frequent planning and focusing on working software throughout the development process.
Step 1 - Goals
Write down the goals (1-5) of the work ahead... why are you doing this work?
Step 2 - Major Tasks
List out the major tasks that you think will need to be completed to finish the project/story. This step is also a good time to start thinking about the areas that will require further investigation or may be the challenging aspects of the work ahead.
If you're working on a full project, make sure to include design work at the beginning! Even sketching out a basic idea of what you plan to build is beneficial to see how to complete the project/story.
Step 3 - Detailed Planning
List out the detailed tasks that need to be completed for the first few major tasks. This step is the most challenging and time-consuming of the planning process.
Also, remember to include investigation tasks when the detailed tasks that will need to be taken are unknown.
Step 4 - Execute and Re-plan
Start working on the first few major tasks that have detailed tasks, but be comfortable stopping to re-plan. Updates to the plan are expected!
Once you finish a detailed task, mark it as complete to feel a sense of accomplishment and to show that progress is being made.
Before starting a major task, make sure to go through listing out the detailed tasks.
Let's walk through an example of a Flask project...
Planning Example
I'm working on a new Flask project that does not use SQLAlchemy, but uses SQL commands directly using psycopg2.
Here's how I have planned out the project.
Step 1 - Goals
First, I come up with the goals for the project, which helps solidify WHY I am working on this project:
Step 2 - Major Tasks
Next, I come up with my initial list of the major tasks that I think will be needed to complete the project:
This listing is what I think will need to be accomplished, but I know there will be changes to this set of major tasks as I start working on the project.
Step 3 - Detailed Planning
Coming up with detailed tasks is the challenging part, because it is very time-consuming and it can be difficult to envision all the small steps needed to complete a project. I think this is where planning shines, as this detailed planning is a first walk-through of how the project will unfold.
I start by coming up with the detailed tasks for the design tasks:
I also come up with detailed steps to get the initial project working, including initializing a git repository and getting the test environment working:
It may seem like too much detail, but just wait until how quickly these tasks can be accomplished after thinking through all the details already.
I've planned out the detailed steps of the first 3 major tasks.
Step 4 - Execute and Re-plan
Time to execute... once a detailed task is completed, mark it as completed. It may feel like a trivial step, but it helps build momentum and keeps track of progress:
After creating my initial plan, the process of drawing out the web page concepts made me realize that I wanted to be able to display the book covers. I decided to add an INVESTIGATE step to figure out if there was an external API available for retrieving book cover images. Re-planning is an expected part of the process!
Once I finish the first three major tasks (i.e. the ones that have detailed tasks planned out), I will need to plan out the detailed tasks for the next major task before actually starting to work on it.
At a minimum, your software project should be working (tests passing and able to demonstrate functionality that has been implemented) at the end of each major task.
Conclusion
This blog post describes the planning process that I go through with my software development work. Planning has been very beneficial for me (both at work and on my personal projects) for two key reasons:
- It helps me overcome procrastination, as I find a lower barrier to work on a small task and then gain momentum.
- It helps me finish projects, as I have a detailed plan to get to the finish line.
I hope this blog post inspires you to utilize planning for your software projects.