The first thing to do in any Software Engineering task: Write a checklist

Photo by Markus Spiske on Unsplash

tl/dr

• Real world Software engineering tasks embed a higher complexity level compared to coding lessons/tutorials due to their necessary integration into a higher order and cross functional system.
• Junior engineers usually rush into coding or architecting prematurely, which leads to frustration and disappointment.
• I propose to start any Software Engineering task by a three buckets-checklist framework in order to improve efficiency and meet timeframe targets.
• I will share my practice and insights that I think can be useful for new software engineers. Would be really happy to discuss further on this topic.

The question is simple: I am a software engineer and got assigned to a task, what should I do first?

When I started my career, I used to jump into writing code on and on. I stumbled on problems that prevented me from being efficient: I shipped things that were not needed, I got stuck on problems that I did not know exist, I build my whole solution based on incorrect assumptions, etc.

I then decided to take a step back and start my tasks by architecting my solution. It was better but not enough. If I lack important insights on the task, it is premature to plan any solution.

What I discovered was the big gap between working on real world tasks and working on coding exercises/tutorials. I learned that I should first observe and reflect about what I do in its whole. I put myself to systematically start all my development tasks by writing down a 3 bucket-checklist. These buckets are Goal, Deliveries and Uncertainties.

I’ll give here first an example of a task, and then I’ll explain my use of the Goal, the Deliveries and the Uncertainties in Software Development tasks.

The Task:
(Our product has user account with profile picture)
Enable Drag & Drop images to update user's profile picture in the web platform. For now, users can only use the selection dialog to select and update their profile picture.
/** 
This example is more suited for Product/Fullstack SWE, but the checklist can be generalised for different schemes as well.
I will stick to this task while providing examples on the checklist. **/

1st bucket: The Goal

The goal is what the task will achieve or enable. In most cases, you will have a single goal, but I usually break it down into different properties.

The Goal:
Make updating user profile something faster, easier and intuitive by using Drag & Drop.
- faster: the process takes less time from end to end
- easier and intuitive: most users must understand the feature right away

When you are at your first Software Engineering job, chances are people will just give you the task without discussing its goal. My take is that it is always important to write down the goal, to discuss and to confirm it even if it seems obvious.

As Thinking about the goal is to reason on your task at the highest level and to fully grasp the impact of what you do. You must start to understand and to reflect about goals so that some day you can set the goals yourself.

2nd bucket: The Deliveries

The list of expected deliveries is what you deliver in order to achieve the goal, also called the task specifications. Having the list written down gives you an overview of what you will have to do, hence a better idea of the workload.

At the beginning of your career, the list of expected deliveries will be provided to you by both your Product Manager (in case of a Product task) and your Engineering Manager/Senior (technical requirements). Here’s a secret: the list of specifications you receive at the beginning is never 100% complete. Making it complete is your job, so please get back to your POCs proactively with questions and propositions.

The expected Deliveries:
- Users can select images to update their profile picture by Drag & Drop from their computer. UX/UI/text will follow what is provided by Product Manager.
- The list of the supported browsers is to be defined. Disable the feature in unsupported browsers.
- Errors case: drag multiple files, unsupported file, server processing errors
- Will work in all prod, dev and local environment.
- Error logs go #here, statistics go #here.

Here are some further key insights I keep in mind while writing down the list of deliveries:

• The edge cases and the scenarios of errors
• The platforms you need to support (web, iOS, Android, Windows, Mac,…)
• Dev and test environments
• Monitoring and logging
• Perspectives of different stakeholders (data, SWE, PM, sales,…)
• Alternatives: Can I achieve the same goal by doing something more simple?

I use the list of deliveries to monitor my progress into the task. I also look at it to select what to work on next. Most of times, I’ll tackle the most risky item left in the list, which would help me to reduce uncertainties. This brings us to the 3rd bucket.

3rd bucket: The Uncertainties

Uncertainties can cause 2 possible outcomes: Either your task gets significantly delayed or it can not be done, from partially to entirely.

My observation is that to handle uncertainties, 3 groups of issues are to be addressed: Dependencies to others, Hypotheses and Critical Unknown.

Dependencies to others:

In real-world Software Engineering, you can not be independent in the realisation of your task. You might need a design, a text, an API, a validation,… from other people. Each one can have their own priority and agenda, which can lead to significant delay for your task.

Clarifying to whom your task depends helps you to plan the communication and coordination with them in order to deliver your task on time.

The Dependencies to others:
- Design from Marc, texts from Alicia (will be off next week)
- Technical solution to discuss with Marion
- File server on dev is being disabled. Need it unlocked for the feature to be fully testable on dev and local environment. See Justin.

Hypotheses

In development, it is indispensable to make hypotheses. The best thing to do is to make hypotheses knowingly, validate them and move forward confidently. The worst thing to do is to make hypotheses unknowingly and discover lately that you had based your work on incorrect assumptions. Be clear on your hypotheses will save you a lot of time.

The Hypotheses:
- Lot of code from the existing flow of uploading an image can be reused by the Drag & Drop flow
- The class AppController is the good place to listen to Drag & Drop event

Unknowns

It is not possible to know perfectly the code base, the libraries and the ecosystem around your task. These unknowns can be source to troubles and delays. What prevents you from achieving your tasks comes more often from the unknowns than from what you already know.

There are 2 kinds of unknowns: known unknowns and unknown unknowns.

More senior engineers don’t know everything, but they have more known unknowns, keep them in mind, clarify them when needed. More junior engineers focus on what they already know and got bad surprises.

The Unknowns:
- Drag & Drop APIs from different browsers (Chrome, FF, Internet Explorer,...). Are they similar or different?
- What if you drag an image from another website? What if it is supported by Chrome only?

To think about your unknowns systematically at the beginning of your tasks helps you to identify them, reduce unknown unknowns. It is a good way to catch up on seniority.

Keep it alive and updated!

This checklist can start small and simple and is not definitive from the beginning. You should keep it alive and updated along the realisation of your task. While the Goal will hardly change, both the Deliveries and the Uncertainties are subject to modifications.

You might discover that some deliveries are not necessary while some other must be added. Big deliveries can be broken down into smaller ones.

Although you can add new Uncertainties along the way, your objective might be to have less and less of them. Dependencies to others might be removed. Some unknowns might be solved while others are finally not important for you task. When you are ready to ship the task, you might have no uncertainties left.

After all, you might not need this

You might already have a very good sense of the Goal. You might always check what to be done carefully before doing them. You identify uncertainties and keep them in mind. You never make assumptions unknowingly. You might have excellent technical skills and collaborative temperament.

In this case, my checklist might not be useful to you. You might have your way to start your tasks, which I would be keen to learn about. There is of course not one single best way to do this.

My best hope is that this can eventually help you to cope with and to help more junior engineers who rush into coding without a sufficient insight of the task.

After the task was delivered and in production, I often check back if the Goal is achieved, either immediately or over time. When it is, I feel happy like a software engineer.

Thank you for reading!