Getting back on a paused/old project

In this post, as the title states, I want to talk about getting to work on a project that was paused for some time, or an old one. There are multiple reasons to have a project put on hold: the budget got cut, the feedback was slow, the project scope changed, the project needed to go back to the drawing board, client straight out forgot about it.

As you see from the list above, none of those reasons is something to be excited about. In most cases, when a project gets paused it’s because the budget is tight, or the project needs to adjust the scope (new features that need to be talked about first).

Sometimes the project is paused for a long period of time and when you get back to it you don’t remember where you left, what was the last thing completed, what was already implemented, if you had tests for all the features, what libraries you used, if you should refactor a certain part because you know a better method now, what was the initial offer and budget, etc.

I kept stumbling upon these issues when the project restarted, so why not mention them here and provide some ways to avoid them?

You’ll find out a bit about organizing, keeping track of project progress and tasks, ReadME files, version history, ADRs, refactoring, and more.

 Organizing your projects

It might sound like something obvious but organizing your projects’ files and assets is one of the most important things, though a lot of people just skip over it. In fact, relying too much on finding things in your email, Slack or what other communication method you use with your client will only slow you down and definitely won’t help you with managing files and tight deadlines.

What I ended up doing is using OneDrive or Dropbox to keep all project details, including the project code itself. Having them in a single place makes things much easier to find and reduces the need to rely on 3rd-parties. You can skip OneDrive and Dropbox altogether if you don’t need to have those synced on multiple devices or with other people.

Create a folder “Projects” and make a separate folder for each project. Then, in each project folder create a structure that suits you. I use something like this:

• Files
• Backups
• Timesheets
• Plugin-name-that-I-created (this will have the actual file and the repository)
• Theme-name-that-I-created (this will have the actual file and the repository)

This is how the folder structure looks on my end.

Projects/
├── awesomeapp.com/
│ ├── 01.Files/
│ ├───── design-files/
│ ├───── images-final-version/
│ ├───── speed-test-results/
│ ├───── initial-offer.docx
│ ├───── updated-offer.docx
│ ├── 02.Backups/
│ ├───── 02042020/
│ ├───── 04042020/
│ ├── 03.Timesheets/
│ ├───── 05042020/
│ ├──────── toggl-timesheet.pdf
│ ├── 04.repository-name/
│ └── 05.another-repository-name/
├── clientwebsite.com/
│ ├── 01.Files/
│ ├── 02.Backups/
│ └── 04.repository-name/
└── membershipsite.com/
├── 01.Files/
├── 02.Backups/
└── 04.repository-name/

You can quickly see how easy it is to navigate through the projects now. I know exactly what I will find in each project and I can store all my projects’ details correctly.

The “01.Files” will have multiple folders based on what I need: images, screenshots, screen recordings, mock-ups, PSD files, contracts, etc.

From this point on you can take this structure and use it as you please. The main idea was that you can create a pattern for your project structure, organizing them so you can always expect where to find things easily.

Keep track of project progress

There is no secret that you need a project management tool to be able to keep things under control. There are a lot of moving parts even on a small project and keeping track of them gets difficult if you don’t write things down.

My favorite tool is Clubhouse, but it might be a little bit of an overkill for simple projects. You can go ahead and try other solutions like Asana, Trello, Click-up. They offer you great control and easy set-up that will allow you to get started in minutes.

Try to take advantage of the sprint/milestone idea. Group your tasks/stories into categories/epics and keep track of the progress over time with the sprint/milestone tool.

Once you do that, it will be easy to go on a sprint (or milestone) and see what tasks were completed there.

This brings us to another part: add comments to the tasks – even when you’re the one creating and completing them. It will help you understand what happened when you go back and look through them. That extra info in the task comment inside your project management tool might save you a lot of time and trouble understanding what it was about.

It’s always great if you can loop the client in the project management tool so they can follow the progress, but sometimes the client is busy enough and he just wants to test or ask about a specific thing, not to search if a specific task already exists or not and see the status.

For this I’d suggest using Slack and integrate it with your project management tool. Most of them have integration with Slack. Create a separate channel where the task updates will be posted and this way they can follow along from Slack.

Create ReadME files

This is one of those things that you might think are just a waste of time. You prefer spending that time doing amazing things while coding, but 3 months pass by and you have to go into that project to implement a new feature. That’s when you realize that your past self was an idiot who didn’t want to take 5 minutes at the end of the day and update the ReadME file, so now you must read through all the code comments to get the bigger picture (if he even left comments in the first place).

It might not happen exactly like this, but you get the idea.

Avoid thinking that, since you’re the one that created the repository and wrote all those lines of code, you don’t need to create a documentation.

ReadME files can help you get a quick overview of how the code works, but they can also provide important details that otherwise you’d only remember if you went and searched in 2-3 different files to understand what a certain class was doing and what a certain method was for.

Yes, you can have standard naming conventions for file name, class names, methods, etc. – that is great when it comes to writing code – but just the class or method name will rarely tell you exactly what the output is.

That’s why you should use the ReadME and record/document all the important parts of your code.

Most of your repositories will be private anyway, don’t be afraid to add as much details as possible in the ReadME file. Or just use a different readme file and add it to .gitignore.

Version History

If the ReadME file from above is a great asset for keeping an overview on the functionality involved in the project, the Version History is ideal to keep track of different implementations on a timeline.

We use Version History to log all the releases and pushes to production.

Create a VersionHistory.md file and decide on a format that will work for you.

We use it like this:

# Version History

## 1.03.01 (released 2020-12-08)
* Fixed some generic bug
* Fixed some generic bug
* Updated library
* Minor update

## 1.02.07 (released 2020-11-30)
* Fix email sending subject

## 1.02.06 (released 2020-10-16)
* Fixed measurement unit conversion

The format used is 1.01.01 where you have major release, minor release, patch fix. You can find out more about that if you search for “software versioning” and see different options as well.

It’s really important to pair the version with the date, this way you get a timeline that puts the releases in context, and you can easily go to this VersionHistory and point where something was done and pushed.

Pair this with the project management tool and you’ll have a very good way to narrow down on specific issues that were logged in there.

ADRs

I mentioned ADRs before as this is somewhat related to the ReadME file step above.

In your ReadME file you can reference your ADRs. ADRs are a great way to keep track of major changes and decisions in your project. I would encourage anyone to use them.

Refactoring

Refactoring is a natural part of coding. You’ll get over your code a few times until you’re satisfied with the results. Even then you might be aware that there is more that can be done, but you decide it’s time to stop.

Getting back on a project that was on hold will trigger this refactoring frenzy.

It might be because in the last months you worked on something similar, you encountered a new library, you found a better way of doing a task, you learned that your method was not that efficient, and so on.

There are multiple things to consider here:

• Does the project need to be shipped within a tight window? Will it allow you enough time to do the refactoring?
• Does the budget allow time for refactoring? You might want to do it out of your own pocket because you’re really invested in the code you write, but at the end of the day you need to remember that you might not get paid for that part.
• Is it fixing/improving something? If it’s just refactoring for the sake of refactoring because you found a more fancy/clean way of coding, it might not be worth it.
• Is it easier to maintain? This is one of the refactoring reasons that I always agree with: If the end product is much easier to maintain, then do it.

I’m sure there are more refactoring reasons, but I’ll just jump to my conclusion.

I like the idea of “if it’s not broken, don’t fix it”.

If major red flags are spotted and your old methods are affecting performance and make things hard to maintain, you should do a refactoring. If not, just log the ideas in the ReadME file or in the project management tool as future tasks.

It’s always great if you can get around explaining to the client why a refactoring would be good and how this can improve the project overall. Some hard facts will help you convince the client, e.g.: it will support this many queries after that, the loading time will drop to x, user experience will by much smoother on checkout, etc.

Other thoughts

I’ll just list some other things that you might want to consider when getting back to a project:

• Discuss all the details again with the client, from the initial offer to what is changed now and needs to be added.
• Check your 3rd party libraries and see if they are up to date (same with WordPress, WordPress plugins). You might not want to update some of them, but make sure you know the current situation. Releases might have appeared in the months you’ve been on hold.
• Check your schedule and see how the project fits into your calendar now.

 

We finally got to the end of this article. Based on my experience as a freelancer, these are the things that I need to keep in mind when getting back to and old project or a project that was on hold.

Of course, you should apply all these ideas from the start so the moment you get back on that project you can go check the folder with the project files, the readme, the project management tool and you’ll be able refresh your memory quickly.