How to Plan an Engineering Project in 5 Easy Steps

OR “How to build a complex application without losing your ever-loving mind.”

Let’s start with a disclaimer: I am not a project planning expert. I’m not a certified scrum master or even a very organized person. I’m just a guy who’s been writing code and creating applications long enough to know that if I don’t plan well, I’ll pay for it later.

If you’re an engineer, you’ve seen it — the obligatory demo video that shows you how to build a blog/to-do list app/wi-fi enabled back-massaging toaster oven in five minutes or less using some shiny new language/platform/SDK. But here’s the problem. Every one of those demos starts with somebody typing a bunch of code. And in the real world, nothing ever starts with the build, especially when the desired end result is more than displaying the words, “Hello World.”

So how the heck do you get to the point where you are ready to dive face-first into code? Well, there are lots of methods to choose from, but at the end of the day, they all come down to careful and thorough planning. Here are the steps I take as an engineer to ensure that I don’t botch the projects that are thrown at me.

1. Understand the actual freaking problem.

No, seriously.

Every project exists to fulfill a need, and until you understand that need, you can’t make a successful plan, much less build an application to satisfy it. Moving forward without understanding the project’s goals is like trying to play darts with your eyes closed. You might be really good, but you have no idea what you’re aiming for. It sounds basic, but it’s so often overlooked that I feel the need to point it out here. Tell me you’ve never seen this scenario:

Manager: We need a micro-service framework built in COBOL that reads XML from a SOAP service and translates it into UTF-8 encoded Swahili before it increments a hexadecimal counter in a brand new No-SQL database and displays the total on our website using non-standard emoji. Can you do that?

Engineer: 👍 [Commences coding.]

We engineers tend to take the spec doc at face value. In default mode, we’ll usually just put our heads down, turn up the music, and start building something without ever asking questions like, “Why are COBOL and Swahili even required?”

And you know what? Sometimes we can get away with that. Sometimes. If the project is small and we’re lucky.

But a lot of the time we wind up building the wrong thing — or, to be more accurate, we wind up building a thing that is, technically, exactly what we were asked to build but that doesn’t actually solve the problem our stake holders wanted solved. Or we might even solve their problem but in a convoluted, round-about, complicated way when a much simpler path to success existed.

There’s got to be a better way…

Because here’s the thing: lots of features that sound simple to non-coders are actually really complicated to implement while other features that look like wizardry and magic to non-programmer-muggles are actually simple builds or even turnkey solutions. It’s our job as code experts to provide that level of insight—to expose the better, more direct, simpler, and more efficient methods of accomplishing our team’s goals. But if we don’t take time to ask the right questions and make sure we really understand what the heck our stake holders are trying to accomplish in the first place, we won’t know to look for those solutions, and we will often find ourselves a month or a year later digging our way out of an unnecessary and complicated hole with nobody to blame but ourselves.

2. Identify any decisions that haven’t been made.

Not once, in all my years of development, have I been handed a large requirements spec that didn’t have at least one gotcha hiding in the scope. There’s always a goblin, a scenario that nobody thought through, hiding in the shadows behind five paragraphs of blah-blah-blah, just waiting to jump out and ruin your day. Do yourself a favor: find it before you’re neck deep into the build and up against a deadline.

And then, sometimes, it’s all goblins.

When you’re hunting for these unidentified questions, remember that the devil is almost always in the details. If, for example, the spec calls for a blog with a commenting system, I can almost guarantee that one or more of the following questions has not been answered:

• Must users authenticate before commenting? And if so, have we accounted for how that will happen? Are we integrating with any social APIs to allow people to authenticate using, say, their Facebook or Twitter account?
• Do individual comments need approval before appearing on the public site? If so, does that apply to all commenters, or just some? And who can approve comments? Do we need to create an admin interface or administrative user role to support comment approval?
• Can comments be turned off for a post before it goes public? What about for a post that is already public? And if a post already has public comments, what happens if we turn off commenting then? Do the existing comments disappear, or do we just remove the comment creation form?
• Can commenters reply to existing comments? If so, how deep can a reply thread go? Have we accounted for nested comments in design across all screen sizes?
• Do we have a plan for dealing with inappropriate/abusive language in comments and/or problem commenters?

That list could go on and on. Every question you ask can, potentially, unearth several more questions that need to be asked. It can be daunting, I know. It’s tempting to skip this step, make assumptions, and get something out the door, but you know what happens when we assume…bad things, man. Bad things. So take the time to really think through the project’s requirements and figure out which decisions still need to be made before you start your build.

A few tips for this step:

1. Don’t present all your questions at once. You’ll overwhelm and annoy the decision makers, and often, one answer will apply to or invalidate several questions. So organize your thoughts, and present them in a way that makes your stakeholder feel valued and helped.
2. If you uncover an unanswered question that will block your progress until it is answered, let the decision makers know. Ask for an estimated response time, and hold them to it. This is not about being a jerk, it’s about helping the team hit its deadlines.
3. If there are two or more options on the table and one is simpler or more complex to implement, communicate that. Help everyone understand what these options will do to the project’s timeline. Technical difficulty is not always a reason to say no to a better option, but the cost might outweigh the benefit, and your decision makers need to have all the facts to make the best choice.

3. Break the project into large functional pieces.

Once you have most of your questions answered (because let’s be honest, you’ll never get all of your questions answered up front), you can start to organize your plan. Are there database changes to be made? Create a document called “Database Changes,” add a bullet point or two to summarize what the changes will need to accomplish, and set aside some time on your schedule to think through specifics later (in step 4). What are the modules/classes that will need to be modified or created? Do the same for each. Are there pieces that will depend on other teams? Note them, and communicate these requirements to the affected teams or your PM. For each piece you or your team will need to build, make a rough, high-level outline of what will need to be accomplished. Sometimes this will send you back to step 2 with fresh questions, and that’s fine. Surface them, and move on to the next functional piece.

Once you feel that your high-level plan is in a good place, you might consider sending it to somebody else for feedback. Up to this point, you’ve been checking the planning work that was handed to you. Starting with this step, you’re doing the planning, so get a sanity check from another engineer or stake holder, preferably someone who isn’t deep in the same project. A fresh set of eyes will be able to see the forest for the trees that surround you, and together, you’ll uncover things you probably missed.

Exactly.

4. Break the big pieces into little pieces and estimate effort for each.

On a smaller or simpler project, you may be able to combine this step with step 3. For larger, more complex projects, I recommend tackling it separately.

Make a list (and check it twice) of every task (naughty or nice…okay, I’ll quit now) that will need to be accomplished to complete the functional pieces you just outlined. They don’t have to be listed in order of execution as long as you feel everything is covered. When you’re done, you should have something that looks like this:

• Create a database table to store comments. Should include a unique ID, the date/time the comment was posted, the ID of the post being commented upon, the commenter’s user ID, the ID of the comment being replied to if applicable, and the text contents of the comment. Be sure to follow our organizational standards and naming conventions. 30 minutes.
• Create a comments model class to support the comments table. Should include basic CRUD functionality and an input validation method. 1 hour.
• Write unit tests for each of the model methods and test them. 2 hours.
• etc.

Maybe you estimate effort in terms other than time. That’s fine. I, personally, am unable to think in any other units, so this is what I do. But the goal is to create a list that you (and your manager) can track against. When a PM asks you how the project is going, you can say, “Well, I’ve accomplished X number of tasks so far. I am currently ahead of/behind schedule, and I have X number of hours/days/units of effort remaining in the project.” That’s so much more helpful than the usual, “Umm, well, I think I’m probably on track.” (You aren’t.)

And again, it is possible (probable?) that you will uncover more questions that should have been asked in step 2 or new functional pieces that should have been outlined in step 3. That’s fine. Surface them now, rinse and repeat.

As before, if you have a coworker or friend who is capable of understanding your detailed plan and really likes you (or just somebody you can sucker into it), it’s a good idea to have them review your list and give you feedback. The better you plan, the better you’ll code.

5. Write documentation before you build.

By this point, you should have a really solid understanding of the project and a plan that you can execute against. If you’re like me, you’ll be itching to dive into code. Don’t do it yet! Write out some rough documentation first.

Document first. Or your inner Gordon Ramsay will shame you.

Now, the type of documentation you write will vary from organization to organization and from project to project, but create something. You’ll probably tweak it later, but this strategy follows the same philosophy as Test-Driven Development: tell your code exactly what it should do, and then write the code to do it. If nothing else, this will help you organize and write cleaner, easier to understand code that is more maintainable when you’re finished.

You might write a technical document. You might outline a series of use cases (if they weren’t already supplied to you). You might design a user flow diagram. But at a minimum, you should absolutely write pseudocode.

I suppose that some folks might argue that pseudocode is not documentation. I think those folks are wrong. ¯\_(ツ)_/¯ Well written pseudocode describes your application’s logic, and if you leave it in the code as comments (I usually do), it will help future engineers understand your code when they modify it. That’s why I include it here.

There are different philosophies and ways of writing pseudocode, and I don’t want to be prescriptive about style. Choose your own poison. For me, what matters is that my pseudocode (A) contains no actual code, and (B) can continue its life as comments in my code when the project is built. I don’t even worry too much about design patterns or best practices here. I just get the logic down. I can always refactor later. An example of pseudocode, the way I write it, would look something like this:

// Fetch all comments for this post from the database
// If we found one or more comments...
    // Create a data array to hold comment data
    // Loop through the comments, and with each comment...
        // Fetch the commenter's user data from cache/database
        // If we successfully retrieved the commenter...
            // Create a new object that contains:
                // the commenter's name
                // the commenter's avatar URL
                // the commenter's profile URL
                // the timestamp for the comment
                // the text of the comment
            // Add the comment to the comment data array
        // End If
    // End Loop
// End If

Then, if you have a colleague or friend who is willing, have another engineer check your logic for flaws before you execute.

I know. This can feel tedious and unnecessary, especially to brand new developers and to engineers who have been at it just long enough to think they can wing it. Take it from somebody who has been programming long enough to know better: pseudocode is 100% worth the time, especially when the project is large and complex. It allows you to think through your application logic without having to simultaneously worry about language syntax, performance, code style, and the quirks of your environment.

Your plan is complete. Go forth and conquer.

Remember what Miracle Max said: “You rush a code plan, you get rotten code.” Or something like that.

Now it’s finally time to write some code! Having taken the previous steps, you can now bask in the glory of knowing you won’t have to stop mid-project to ask a question about scope or even figure out how the application should work. That’s done. All you’ll have to worry about is writing the cleanest, DRY-est, most testable and efficient code you can write. That’s enough on its own, isn’t it? And just imagine, with that kind of focus, how much more smoothly your code reviews will go and how many fewer misunderstandings and “bugs” that are really “I built this incorrectly” errors you’ll have to deal with now. You’re welcome.

Is there another process that works for you? Do you have suggestions about improvements I could make in my process? I’d love to hear them! Leave a comment or response, and let me know!

We’re always looking for amazing people to join the Creative Market team. We value our culture as much as we value our mission, so if helping creators turn passion into opportunity sounds like something you’d love to do with a group of folks who feel the same way, then check out our job openings and apply today!