TL;DR Software engineering projects. Quick guide, explained simply.

TL;DR

Every project needs well-defined expectations at every stage of the process, and it’s usually up to a few people to do it. The more mistakes you make in these early steps, the more likely you will change the scope during the project and make things worse later — delays, bugs, missed functionality. In most cases, the software engineering & testing teams will pay the price for these poorly defined expectations. That sucks!

What are typical steps to get projects done?

1. Define.
   It should be obvious what high-level expectations you are looking to achieve and why they’re needed. This step doesn’t define HOW, but mainly focuses on WHY and partially on WHAT. Seek feedback from teams before you commit to the project and communicate to stakeholders.
2. Refine.
   Design & Product (with little help from Engineering) refine what you need and how it will look. Explore different options, ideas and agree on all the functionality that hopefully doesn’t go beyond engineering limitations. Most of the focus goes on WHAT. This is the time when your project will gain shape and can be split into different teams. Ensure representatives from each discipline have input on the direction as it will save you from many surprises later.
3. Get it done.
   Review all requirements, plan the work, split between teams. Any mistakes or sloppiness in the previous steps will affect timelines, especially if the teams have to chase for more information or deal with too much ambiguity. Teams decided HOW, and knowing the platform’s limitation, will want to adjust the WHATs to meet the deadlines.
4. Test & Deploy.
   Everything should be tested to make sure all three previous steps are aligned and make sense as a whole. At this stage, you make sure that HOW and WHAT matches the expectations defined for this project. Test on different devices, add automation to streamline the future improvements, make sure it actually works.
5. Done.
   The project is DONE when the teams have a chance to clean up the side effects of their work, not when it went LIVE. If you leave things without reaching done-done state, you will generate tech debt which gets costly pretty quick. Any debt comes with interest, and you (mainly the engineering team) will have to pay it.
6. Monitoring & future improvements.
   Review the product regularly and make sure it works as intended. Keep an eye on bugs and errors. If possible, address any UX concerns, and don’t assume your work is done, and the project can be put into “maintenance mode” for the next two years.

Home DIY door replacement as an allegory for software projects.

Let’s translate software engineering into a home improvement project. If replacing doors we can call a project, of course. It sounds like a pretty minor job, but I’ve learnt it is more complicated than I thought, especially when doing it for the first time. I just remembered a classic office situation “I need your help, it will take you only 5 minutes” :)

I recently decided to replace one of the internal doors with bi-folds. When I finished the installation and failed, I realised that this is exactly what happens within software engineering when the initial project fails — primarily due to not well-defined requirements, insufficient research, poor preparation etc. Similar issues contributed to my misery after installing the door. After hours of fight in heat, the final “product” looked good, but “bugs” in functionality added more work for the next day. The “go live” date had to be moved!

Let’s go step by step and identify what happened and what went wrong.

Preparation for my little Door Replacement Project.

We decided to replace our regular bedroom doors with a new ones. So let’s talk about the most critical parts of this plan.

WHY

• We need doors that will be smaller, space-saving.
• The bedroom is on the south wall. It would be nice to let the light fall into the rest of the house when the doors are closed (and they will be in summer due to aircon).

WHAT

• Bi-fold doors.

CHALLENGES

• Is it possible to fit bi-folds into the current door frame?
• Can I do it myself, or I need a contractor to do the job?
• Cost — not that important.
• Timeline — Finish the job within a month before we start living together.

Defining door-related requirements sounds very simple and a bit more natural, and you must apply the same principles to software engineering. Think before you do, agree on what you need, what is important and communicate it the best you can. This way, you will avoid confusion, assumptions, overblown costs, underestimated timelines and disappointment. It is essential to review all requirements and ensure the project is even possible before it officially starts.

I went on a journey to investigate the challenges, estimate cost and effort. I had to learn a little more about how such doors look and how they are installed. Since I never used such doors, I’ve ended up watching some YT videos. In the end, the conclusion was: it should be possible to install them in the current frame and should be enough to do it on my own.

Figuring out some minor details…

The project is viable, and we want to proceed. High-level requirements have been defined, and we could move to another stage and focus more on WHAT exactly we need, where we can find it and sort out all the logistics.

• Colour: Just white, nothing fancy.
• Style: Simple, nothing fancy
• Challenge: Should we buy or build from scratch?

My door example is simple. You will likely need UX and UI teams to go through iterations of users testing, designs and functional requirements. Make sure the engineering team provide input at this stage. They will bring a lot of improvements to your projects, and by the time it hits them, they will already understand what needs to be done and how to approach it. Transparency is the key, and engineers need to be involved early. Leave this typical waterfall approach behind and involved key persons as early as possible.

With a limited choice of doors on the market and my skillset not even close to building such a thing from scratch, we decided to buy new doors.

There is time and place for both built vs bought, and I feel that way too often, we pick off-the-shelf solution for simple challenges- they come with a cost, mainly in the form of performance when software engineers decide to go with a heavy library that does everything, instead of writing a couple of small functions that do exactly what is needed.

This is a manual on how to install doors in frame. Doesn’t that look like typical documentation for some API? Hard to understand, missing details and hard to “navigate”. I was asking myself, “and that’s it???” :)

Installation, deployment, testing…

It took me a while to understand the “documentation” and figure out which part goes where, how the doors should be fitted and where I should start not to screw up. The last thing I want to end up with is a new door frame and all the mess that comes with it.

When you assign tickets to engineers and don’t explain them during refinement or planning sessions, they will go through a similar struggle — trying to understand what the ticker says and wondering if they haven’t missed anything. The worst part of this is that they can’t even ask for clarification, and any attempt for clarification is nearly impossible.

I properly invested my time reading the requirements, trying a few things, laying down all the parts, and figuring out where they go. Slowly it all started to make sense, and instructions became clear. I was lucky that this manual was just “good enough” and the whole project is simple.

Like every typical software project, things look complicated and sometimes impossible when the team looks at it as a whole. Don’t stress out. When you include the team and help, they will go through the requirements step by step and slice them into small, manageable chunks. Whatever works for the team to digest the content and split the impossible project into tiny manageable bits. Now they are ready to deliver.

It’s just proof that I didn’t think about every detail during my earlier planning, and I missed a few critical bits. The project’s requirements were not entirely up to scratch. Ohh… let’s fix it and test it again (properly!).

Teams should always test their changes or you might end up with pretty but non-functional doors.

Doors work, and “customers” are happy. What’s next?

Project done! … Right?

The doors are fitted, they open as expected, work smoothly and do what they were designed to do. Should I consider the project done? What about the mess? I can’t leave everything in that state, and I doubt you would do it either. The old doors right in the middle of the hallway. What about extra holes I made by mistake? What about scratches on the door frame? What about unpainted surface of the door? And look at this mess on the floor!

The project is DONE when the team had a chance to clean up all the side effects, not when it went LIVE. In many places project is considered done when it’s live and started making money. Old code is never cleaned up and old APIs are not decommissioned. That’s very short-sighted and will lead in the future to a never-ending battle between New Feature vs Cleaning the Backlog.

If you leave things behind, you will pay for it sooner or later. It is hard to maintain legacy code and “almost” not needed servers, apps and APIs. It takes a toll on the team and often means extra cost and complexity.

That’s where my project ended at the moment, as I have more things to do before finishing up these small details. We are not moving into this room yet, and when I get to the last stage, which is going to be wall painting, I will finish off the doors and clean up these few little things left behind.

I did exactly what companies often do! I found an excuse not to “decommission old code and clean up the backlog”… but you know the difference?

I have visibility of what is ahead, the next projects and how I can optimise my time. I can decide not to clean up the backlog now because I plan to do it a bit later as part of something else and, as a result, waste less time and be more efficient.

After the cleanup, my project is going to be done-done ;)

Future planning twist…

ALWAYS make sure the teams know what is coming in the future. This will help them to plan better, be more efficient and deliver better quality. I’m not too fond of companies where engineers know only about their work 2 weeks ahead and nothing beyond that.

But I guess this is a topic that deserves a separate blog post…