How to Write A Software Program Roadmap

(Article appeared originally here: How to Write A Software Program Roadmap)

You know what one of the most common causes of failure is for software projects? You don’t have a plan. Unlike building with more solid materials in construction, you can start making software before you know what the hell you are doing. Writing a program roadmap helps you make decisions earlier when they cheaper, and give you a reference point to make sure everyone involved is working towards the same goals.

The Project Plan Problem

The challenge with writing project plans is that they have to serve two audiences: The project owner, who needs a clear picture of what is getting done, and the production team, who needs to know how it’s getting done.

This leads to writing plans that serve one purpose but not the other. Either the plan is vague and generic, and leads to misunderstandings about how particular features work. In the other extreme, you have 5o page technical specification documents that are tedious to read. No one wakes up in the morning, pours a cup of coffee, and settles in to read the morning technical spec.

Tech Specs and Soulless Developers

Technical specifications miss out on the goals and purpose of the project. It can tell me the validation rules for all 18 fields on a form page, but it doesn’t tell me the ‘why.'

You need to communicate purpose to your development teams. If you are a project owner that doesn’t, because you don’t see why they would care, don’t think it’s relevant, or believe it isn’t the developer’s business then you are causing harm to your project. Developers without purpose and reasoning are left to make technical decisions based on a best guess of your goals in the best case and implementing the easiest solution that meets requirements without any regards for quality in the worst case.

Despite these downsides to technical specifications, there still needs to be some digging into detail. Architects spend countless hours reviewing blueprints because fixing misunderstandings with an eraser is much cheaper than a bulldozer. Deleting code is cheaper than tearing down brick walls, but the efficiency of planning is still present.

With any project, you have to make a lot of decisions. You can tackle them early on when it’s cheap to fix or address them later in arguments about scope creep and deadlines. It’s up to you.

So, how can you write a plan that captures the gestalt of the project while providing enough detail to make implementation clear?

The Pyramid Plan: Top-Down Documentation

Think of a program roadmap like a pyramid: We are going to start at the top, a small beacon that guides the entire project. From there we’ll work down into more and more detail. The beginning parts are smaller and cover a wider scope. As we move down the pyramid, the sections get larger and more in-depth. We start with a simple statement about the project as a whole and then move down to several larger bricks explaining each part of the project.

The Objective — Why Are We Doing This?

The first part of your project plan is the objective statement. Keep it short and sweet: one to three sentences about why the project exists in the first place. Here’s an example:

XYZCommercial.com is a platform for XYZ Real Estate’s commercial property division. The site will display available commercial properties in the Atlanta area. The goal is to act as a lead generation platform to attract and collect contact information from potential buyers.

The 1,000 View — How Are We Doing This?

The 1,000-foot view explains the strategy for accomplishing the objective. It paints in broad strokes. This section should be 1 - 3 paragraphs that describe the key features of the site. For XYZCommercial, we would mention having large photo galleries, a lead capture form that integrates with an internal CRM, and the ability for prospects to quickly search through properties.

User Types — Who Is Doing This?

All technology is communication, and all problems are people problems. So the next part we’ll want to document is who is going to be using our application, and segment them into categories.

User types are the different kinds of roles people will have when they interact with the project. Here are some recurring ones from my project planning template:

• A visitor is a person who is just visiting the site.
• A user is a person who has an account.
• A customer is someone who has made a purchase.
• An administrator is someone who has internal access to management tools.
• A developer is someone who works on the technical side of the application.

Your app may have more specific roles. A membership site may have a trial user. People can also shift as they take actions within the applications. A visitor may become a user that later becomes a customer.

Building Blocks — What Are We Using?

The next part of the documentation is going to be the main items with which the users interact. Developers are familiar with terms like ‘objects’ and ‘models’ for these blocks. I prefer using a term with less technical baggage.

These are the ‘nouns’ of the application. In entry-level computer science courses, students are asked to play a game called ‘find the nouns’ as an introduction to data modeling. You look at the problem statement and identify nouns that sound like something that our application will model. Let’s play with our objective statement:

XYZCommercial.com is a platform for XYZ Real Estate’s commercial property division. The site will display available commercial properties in the Atlanta area. The goal is to act as a lead generation platform to attract and collect contact information from potential buyers.

Here, we find the building blocks of our application: properties, contact info, buyers. For each of these, we will write a brief description of what these are and how they relate. The more complex your application, the more value this section provides.

A note here is that as inhuman as it is, sometimes people will be objects in this structure. This is an important distinction. User types are for people that interact with the application in some fashion. Let’s say you are a college professor, and you are using a class scheduling tool. The tool has a roll of all students in each class, but only you and your TA use the system. In the case, students would be considered objects, not people.

Sorry kids.

Use Cases — How Do We Specifically Do This?

We have the core parts of our system documented: who uses the system, what they use it for, and what they are trying to achieve. Now it’s time to tie them all together. We have the nouns of our system; now it’s time for the verbs.

Already some of the connections should start to appear: An administrator can post a property. A visitor can submit contact information. A visitor can turn into a lead. A lead can turn into a customer.

A standard format for documenting these is called a user story. Here’s the user story template:

As a <user role>, I want to <action> so that I can <reason>.

In our commercial property example, it might look like this:

As a visitor, I want to submit my contact information, so that I can inquire about a property.

These can be useful as a high-level acceptance case. If a visitor can provide their contact information, then the project has achieved its goal. The problem with user stories is to me these are still too vague. This story makes many assumptions.

Instead, I like to write use cases. The skeleton of a use case has the same bones of a user story: a person, an action, an outcome. Use Cases have a bit more meat on their bones and go into more detail as to how this is accomplished. Here’s a use case for the previous story:

If a user is interested in a property, they will have the option to express interest in the property. They will do this by first clicking a button on an individual property page, then filling out and submitting a form with their first name, last name, email address and phone number. This will create a lead, and that lead is then sent to a 3rd party CRM.

This style provides some implementation details and further guidance for the development team.

The Benefits of a Clear Program Roadmap

This program roadmap gives you a clear idea of the work in a the project, and, more importantly, why. The process of writing the plan can help you figure out priorities and make decisions earlier in the process. This will also help keep everyone on the same page as the project moves forward and help settle disputes.

(To download a Sample Program Roadmap visit the original article here: How to Write A Software Program Roadmap)