Hartley Brody

While there are tons of resources designed to help people learn to code, there aren’t as many resources for helping people learn to build software products, at a higher level.

“Writing code” is largely a vocational skill, just like swinging a hammer is – but presumably you’re using that skill to actually build something.

In my experience, the reasons software projects fail – take too long, go over budget, are too complex – isn’t necessarily because of bad coding practices. It’s because there was too much focus on writing code, and not enough on building a product.

It’s deceptively simple (and all too common) for a non-technical person to come up with a few sentences describing an idea, shoot it to someone with coding chops and say “code this for me.”

It’s essentially the modern-day equivalent of someone sketching a building on a napkin, handing it to a carpenter and telling them to start swinging their hammer.

There are often huge structural decisions – as well as a million tiny implementation details – that need to be fleshed out before you even start writing a line of code.

If the first thing you do with a product idea is start coding, your project is almost certainly doomed.

Why You Need a Detailed Specification

If you don’t have a detailed plan for how you’re going to build your product, then your engineers will inevitably make all sorts of seemingly small decisions that might not be in line with the original product vision, or what the business stakeholders need.

Those decisions will then have to be rolled back once the business stakeholder discover them, wasting a lot of time and energy, and also undermining the entire codebase.

Engineers: What color should we make the carpets? Oh, they didn't specify? Okay, well uh, red then?
Business (after walking in and seeing the red carpets): Red is our main competitor's color! How could you have chose this? Tear them up and recarpet the office with blue!

If you don’t have enough detail, then you’ll end up spending a ton of time writing code that ends up getting thrown out or refactored very quickly. This is the main source of delays in projects that have taken too long or gone over-budget.

If you had specified the carpet color from the beginning, then you wouldn’t have to lay it down twice, and spend the time and effort ripping it up in between.

But in a software project, sometimes these last-minute refactors are even more problematic than simply rewriting sections of code. Instead, they’re more akin to trying to change the foundation of a building from cement to wood pylons after several stories have already been built.

It’s not just that you have to change one or two pieces of the code – even small changes can have big ripple effects across the codebase. There are tons of abstractions and relationships in even seemingly simple pieces of software. Those all get created based on assumptions about how the finished product should look.

A real-world example of a seemingly minute detail that could have a huge implications on a project is deciding if a user is allowed to have multiple email addresses or just one.

Adding support for multiple email addresses – after the assumption was that there would only be one – isn’t simply a matter of adding a new field to the user table, it can have implications on the login system, notification and emailing systems, billing and admin, profiles, sharing and lots of other interconnected systems.

It’s extremely important to get as many things right as you can in your first pass of writing code.

The best way to avoid ambiguity and the problems and delays it creates is to come up with a plan. This should be done with all of the stakeholders – business and technical – working together, to explicitly lay out how the most important pieces of the product will look and function.

How this Process Developed

Before I was a freelancer, I was employee #1 at an ad tech startup. We weren’t a traditional single-product company. Instead, we built dozens of products, some of which were user facing, while many were internal ad- or analytics-related products just for us or our partners.

We had lots of product ideas that we wanted to test, but we couldn’t afford to spend months bringing them to market. We had to ship quickly, experiment and iterate, so our product development process had to be very efficient.

Genetics researchers study fruit flies because their lifespans are so short, meaning researchers can observe many generations very quickly.

We built (and threw away) so many products in such short time periods, it proved to be a similarly effective laboratory for testing product development strategies.

We experimented with several different iterations of product development processes and were ruthlessly honest about what was working and what wasn’t. I learned a lot about building products in my time there.

I’ve since taken what we learned and the general processes we developed and adapted them for various clients across a dozen different projects.

The Product Spec

The first step is to produce the Product Spec. This is a non-technical document and should usually be written by the client or product owner, with assistance where needed.

I have a Google Doc template which is essentially a structured list of questions designed to to help the client brain dump their ideas about the product.

The exact questions change from product to product, but there’s usually sections about the following:

• Users: Who are they, what are their goals, why are they using the product?
• Features: What features are required, what are nice to have, and what are backlogged for later?
• Components and Screens: What are the pages or URLs the product will have, and are there non-user facing parts?
• User Experience (UX): Taking what we know about users and what we want to build, what are their main flows and experiences within the product? How would a user perform the core actions in the product?
• Open Questions: What are the things we don't yet know or made assumptions about that should be tested to make sure everything is viable and will work like we expect it to? We'll list open questions and then try to answer them within the document, to have a record of potential problems and the solutions we came up with.

After the Product Spec is complete, the client will have a thorough document that describes the Minimum Viable Product (MVP) product as well as a backlog of potential features to be added down the line.

This can be used to guide a product road map, to help with a pitch to investors, to find an outside development agency, or just generally to help the client wrap their mind around what they’re building.

The Technical Spec

The next step is the Technical Spec. This is a technical document that lays out the high-level structural and architectural decisions that need to be made before you can start writing software.

While the Product Spec describes what we’re building, the Technical Spec describes how we’re building it.

It’s important that the Product Spec is finished and agreed upon before beginning work on the Tech Spec, so that time isn’t needlessly spent designing a system on top of changing requirements.

While the Product Spec might be similar to an architectural rendering, showing the glassy facade of a building from 1000 feet away, the Technical Spec is more like the blueprint, working out some of the important structural details at a lower level.

For the Technical Spec, I’ll often do the bulk of the writing. If the client has in-house technical resources, then I’ll work with them to ensure their approval.

Common sections include:

• Core Technology: Programming languages, frameworks, open sourced libraries, public data sets, important third-party APIs. What are the core pieces the product will be built with?
• Data Models: What are the main objects that this product deals with? What are their properties and methods? What are the relationships between them?
• User Flows: As users follow the key flows from the Product Spec, what will happen at a tech level? How and when will things be processed? When and where will data be saved?
• Technical Diagram: How will systems communicate? How will 3rd-party services be integrated?
• Infrastructure & Ops: Hosting? Deploying? Logging? Testing? Monitoring? Analytics?
• Open Questions: Are there technical feasibility issues? Do we need to hack together quick prototypes to make sure something is possible? Just like with the Product Spec, we'll enumerate these and then try to go through and answer them before moving on to the next steps.

Once the Technical Spec is complete, the client will have a very detailed picture of the complexity and scope of their product.

If there were questions of technical feasibility, those will hopefully be answered. If they want a quote for how much time it will take to build, or at what cost, this document will make those answers very clear.

Next Steps

Once we’ve gotten to this point – both a Product and Technical Spec, signed off by the necessary stakeholders – now we’ve got a much clearer sense of what needs to be built and our plan of attack.

We’ve taken the back of the napkin sketch of the office building and turned it into an architectural rendering as well as a clear, detailed blueprint for what needs to be built and how it’ll all fit together.

At this point, we’ve laid everything on the table and can decide how we’d like to proceed.

I’ve had clients who looked at the Product Spec and realized they could actually just build their product using an off-the-shelf survey tool for $10/month instead of paying thousands for something custom, like they had planned.

Sometimes clients will take the detailed Tech Spec and look for cheap overseas coders to build it on eLance and oDesk. We actually did this for some projects at my last startup with great success.

Sometimes the process of writing these documents is so informative that the client decides to take it in a completely new direction, and that’s okay. There’s no commitment that we have to work together moving forward – although I’d usually love to!

If they decide to move forward, we can come up with a quote for the full product or break it down into smaller deliverables.

There should be very few surprises at this point, so it’s much more reasonable to set deadlines and time estimates than it is when you just have a few aspirational sentences about a product.

Just Enough Process

Now some of you might be thinking, “Top down, waterfall-style approaches to building software are bad! The market changes, issues crop up, you can’t possible enumerate everything up front! You need to be agile.”

Surfacing technical issues to clients – as well as frequent, clear communication – is definitely part of the process. But setting out without a plan other than “being agile” is a great way to waste a lot of time chasing dead ends and writing code that you have to throw away or constantly refactor.

I also only try to employ these steps for building Minimum Viable Products (MVP), or adding features to existing products, so we’re just fleshing out the minimum feature set to start testing and learning about user behavior. The documents never describe more than a few weeks of actual development work.

The Product Spec includes a backlog section for features the client would like to add eventually, but this can change once we start leaning more about how customers are using the product.

Don't be Dogmatic

As with many things in life, it’s important not to be too dogmatic about always doing things a certain way. For really small features, these steps might be overkill, while some of the questions might not make sense for certain kinds of products.

I generally think of these steps as guidelines, to help guide the product development conversation, and ensure all stakeholders are on the same page about where we are in the process and what problems we’re focused on solving.

If you think you could use my help on your product, drop me a line! :)