Behind the code: project planning

Posted by: Peter Jones on

In this new series of articles, Behind the Code, I’ll be looking at the tools and processes that I’ve put into place to make me a more efficient and effective developer. I’m hoping to share my experiences, and while doing that, refine the way I work using your feedback.

Today, I’ll be talking about project planning, the process of breaking a project into tasks, and estimating the effort to complete those tasks. The artifacts generated during this process can then be used to create a proposal for a client, cost estimations for your boss, or even the start of your project documentation.

File Formats and Tools Matter

If there’s one thing I’ve definitely learned the hard way, it’s that the tools I use today aren’t necessarily the tools I’ll be using tomorrow. A better tool might come along, or I might be forced to use another operating system where my preferred tools aren’t available.

I avoid binary proprietary file formats like used car salesmen. It’s so important to me that it’s my first rule:

Rule 1: Use plain text files when possible.

No matter which platform you’re using, you can read and work with text files. If you happen to use a platform with good command line tools (anything Unix based), you have a powerful system available for finding, searching, and transforming text files.

Text files rock, and what’s the best tool to edit them? Being a developer, using a text editor shouldn’t be unfamiliar to you. As a matter of fact, it should be the tool that you’re most comfortable and efficient with. If there’s only one thing you can call yourself an expert in, it should be in using your text editor.

Tools for Project Planning

There are several tools you can use to do project planning, all while working with nothing more than plain text files. My tool of choice is Emacs, using the amazing Org-Mode package.

The tools that you pick will depend completely on you. In this case, the process is slightly more important than the tools. Don’t get me wrong though, a good tool can make a big difference in your workflow.

I like Org-Mode because it provides a lot of functionally, yet at the end of the day everything is just plain text. I can easily keep my project files in a revision control system, and use tools like Ruby and grep.

Breaking a Project Into Features and Tasks

The first step for planning a project is breaking it into smaller pieces. I like to create a shallow hierarchy, where I break a project into features, and then take those features and break them down into tasks.

Features are usually the bigger chunks that your client or boss would know by name. Since features are big chucks, you can’t estimate them correctly, or think clearly about their dependencies without breaking them down further.

By breaking a feature down into tasks, you virtually walk though the implementation of that feature, thinking about dependencies and potential problems that you’ll have along the way.

While breaking a project into features and tasks, don’t think about time estimates, only process. Work through the steps you would actually perform to implement a feature in your mind, recording them in your project plan as tasks.

Below is screenshot from Emacs, showing the outline I’ve created for a fictional social networking application. Org-Mode allows me to fold the outline at any level. Here I’m viewing just the outline headings that show two features, broken down into tasks.

Folded

Folded

While I’m creating the feature and task breakdown, I leave myself little notes just in case the headings are too vague and a few weeks later I’m not sure what the hell I was talking about.

Below is a fully expanded version of the outline from above, so you can see the notes. Later, these notes can be expanded and used as project documentation or a client proposal.

In Org-Mode, the tab key is used to expand or fold an outline. This makes it very easy to see just the part of the project plan that you’re interested in.

Expanded

Expanded

Estimating the Tasks

As I mentioned before, a feature by itself is too vague to estimate. But now that you’ve broken each of the features down into tasks, you should have enough information to estimate the effort of actually implementing those features.

I’m not going to dive too deeply into the art of estimating in this article. That said, put your estimating cap on and let’s get to it.

The best way to estimate your tasks is to begin with the first task, and work through them one at a time. I prefer to break my tasks down into hours and minutes, usually in 30-minute increments.

If you come across a task that will take more than a workday to complete, you need to break the task down into more tasks. It’s important that your tasks are granular enough, I personally don’t like my tasks to take more than 5-hours. Along the same lines, any task that takes less than 30-minutes, however, should be reviewed to ensure it has been thought through enough.

Below is a screenshot showing estimates assigned to each task. I like to switch Org-Mode into column view. Org-Mode makes it easy to see summations of task estimates using its handy column view mode, which turns your hierarchical outline into a table.

In this screenshot, I’ve assigned estimates to each task. The features now show the total estimates for their respective tasks, leaving the top headline (the project name) with a total estimate for the project. Org-Mode automatically summed the time estimates for me, I only assigned estimates to the tasks themselves (in purple below).

Columns

Columns

Presenting the Project Plan

With your task estimates completed, you’ve collected enough information to present a proposal to a client, or a project plan to your boss.

If you’ve been using a software tool to create your project plan, it probably has an export feature. Org-Mode can export your document to HTML, LaTeX, and even a cleaned up ASCII text file.

Even if you’re not using a tool with an export feature, you’re a software developer right? Write a script that will transform your text file to something useful for your situation.

As an example of a client proposal, I’ve exported the project file into a cleaner PDF file for my fictional client. If this were a real proposal, I would add additional notes, along with details about the cost of the implementation.

Using the Project Plan During Implementation

Why do all the work of creating a proposal, only to let it collect dust? When it comes time to implement the features that you created a spec for, why not turn them into a to-do list?

Using the Org-Mode ability to manage to-do lists, I turned the estimated tasks into to-do items. With Org-Mode I can “clock in” to a task, which starts a timer. When a task is complete, I mark it as being done, and then I can compare the time I spent working to my estimates.

Below is a screenshot where I’ve completely expanded a finished task so that you can see the meta-data that Org-Mode was adding to it when I used the timer on a task and then marked it as complete. You can also see how a headline can be turned into a to-do item.

Tasks

Tasks

It’s much more useful to switch back into column view for the comparisons between my estimates and the clocked time. The below screenshot shows my outline back in column view, this time also showing clock time summaries.

This is a good example of how Org-Mode can collect the meta-data in your text file and then present it to you in a more efficient way. You can even edit the data in this table-like view, and Org-Mode will do the right thing.

Clocked

Clocked

In addition to column view, Org-Mode has several ways to generate reports from your data. I especially like the agenda view.

With the agenda view, you can see which tasks you’ve scheduled for specific days. I find it very useful to spend a little bit of time at the end of my day, and schedule which tasks I’ll be working on for the following day.

In the morning, I can review my agenda and start working with a clear idea of what I should be doing. This really helps with any tendency to stall or procrastinate during the first hours of the day.

Article Artifacts and Further Reading

I chose to show screenshots above so you could get a feel for how a good tool like Org-Mode can provide a nice interface for project planning. The nice thing about Org-Mode is that you’re just working with a text file, and if you open that file in any other text editor, it doesn’t look foreign.

Below are links to files I created while writing this article. Open the project plan in your favorite text editor and compare it to the screenshots above. Try opening it in Emacs and see what happens.

If you’re looking for more information about Org-Mode, the main web site is a great resource. There is a fantastic manual, and a very responsive mailing list if you have any questions.