So you have a new idea for a piece of software… how do you develop the idea enough to know if a developer can build it, or how much it is going to cost?

This is where your Software Specification (or spec, or requirements) come into play. Poor, or incomplete requirements result in missed costs, poor user experiences, and ultimately worse products. Whether you're an enterprise stakeholder or a potential startup founder, you don’t want that.

So, how do you do it well, and on a budget?

What is Speccing Software

Speccing Software, often called Requirements Gathering to seasoned software professionals, is basically the art and science of defining what your software needs to do. A spec can be as small as a photo of a whiteboard, or as big as a 3,000 page waterfall style document outlining every single detail.

There are obviously pros and cons to different approaches, so let’s examine some of those in the next section.

Problems with Speccing Software

Different approaches to defining the features of a software application ship with different pros, cons and problems. Let’s take a look at some of the more common (and extreme) approaches.

Back of the Napkin / Whiteboard Spec

This approach is likely the simplest form of requirements gathering. It’s where a couple of stakeholders sit in a meeting room (brick or virtual) and draw out some simple ideas (wireframes, flows, etc) on a whiteboard or piece of paper. Let’s take a look at the pro / con of the Whiteboard approach:

Now, let’s take a look at the opposite end of the requirements gathering spectrum: the Waterfall Spec.

Waterfall Spec

This approach is the polar opposite of a quick whiteboard or napkin spec. In a waterfall approach, a Product Owner or Project Manager spends an immense amount of time understanding stakeholder software goals. Once the goals of the software (what business need it is filling) is completely and comprehensively understood, the PO / PM sets out to work building an incredibly detailed document of every single feature, validation, button, input and other requirement the software needs. These documents are often thousands of pages long. So, let’s look at the pro / con of the Waterfall approach:

We can see between these two approaches, each have some great pros, and also some pretty significant cons for enterprises and startups.

At Take2, we have developed a requirements gathering process that attempts to incorporate all of the pros, while eliminating all of the cons, and we’re excited to share it. But first, we need to understand the nature of the problem we’re solving.

What’s the point of the spec?

What do Developers Really Need to Understand from a Software Spec?

The point of software requirements is, in essence, to efficiently relay exactly enough information for an engineer to develop the specified functionality.

Additionally, developers need to be able to consume the information quickly. How long will it take your devs to have a holistic understanding of a 3,000 page document? A long time, right?

Breaking it down into pieces, developers and software engineers need to understand:

• Who the app is for
• What problem it is solving
• What it looks like (the User Experience)
• Specific business functions (what it does)

Creating Software Specs Quickly & Easily

Solving for these items, while trying to stay mindful of time, cost, and fun, we have developed our own way of speccing new software. We call it the Persona Spec.

So, how do you get started creating your own Persona Spec? Glad you asked….

Step 1: The Elevator Pitch

The Elevator Pitch is your 15 second explanation of why your software matters, is cool, disruptive, etc. It needs to be compelling for the people you’re trying to convince to use the software. Here’s an example:

The Occam’s Protocol App - Elevator Pitch

The Occam’s Protocol App is an iOS and Android app that allows users to easily manage their Occam’s Protocol workout regimen, based on the workout plan by author Tim Ferriss in his book “The 4 Hour Body.”

Even though it is short and simple, this elevator pitch would be very compelling to anyone who is a Tim Ferriss fan, and has read his book The 4 Hour Body, or tried to follow Occam’s Protocol on their own. They instantly understand that it can be somewhat difficult to keep track of, and would very much be interested in having an app that helps them.

Subscribe to 🎉💪 content!

Get our tech articles once a week, free of spam.

Subscribe

Step 2: User Stories

Once you have established your Elevator Pitch, you need to work out at least one User Story. This should be a made up story about your key user successfully using the app you’re proposing to build. So adding that in with our Elevator Pitch might look something like:

The Occam’s Protocol App - Elevator Pitch

The Occam’s Protocol App is an iOS and Android app that allows users to easily manage their Occam’s Protocol workout regimen, based on the workout plan by author Tim Ferriss in his book “The 4 Hour Body.”

User Story: Jeff

Jeff has recently read “The 4 Hour Body” and is specifically interested in Tim Ferriss’s approach on building muscle, termed Occam’s Protocol. Jeff is also, however, a busy professional and father of 3, and does not have time to build a series of spreadsheets and documents to manage his Occam’s Protocol workout schedule and progress.

Instead, Jeff performs a Google search for “occams protocol iphone app,” and finds there is indeed an “app for that.” Now, instead of spending hours performing starting weight calculations, building spreadsheets, and logging data, Jeff downloads ​The Occam’s Protocol App (TOPA)​, and when he arrives at the gym, the application guides him through the startup process, gathering all the required information in a few clicks, and performing all of the necessary calculations based on Jeff’s input.

A couple of days after Jeff’s first workout, ​the app​ notifies him that it’s time for his next workout tomorrow. The next day, Jeff heads to the gym, opens up ​the app, ​and the application tells him exactly which exercises he needs to perform, and how much weight to use.

Jeff continues this process through the 60 day Occam’s Protocol cycle, gains 20lbs of muscle, and looks great for his spouse.

Note that we follow Jeff from the start of his journey to our app, including a basic idea for how Jeff might find our application. These types of things are important context for software developers, because they will impact how the application is designed.

Congrats! You have now completed the first step of your full persona spec!

Step 3: Creating Base Personas

Now that you have an Elevator Pitch and User Stories, it’s time to start writing out your Persona Spec. To do this, simply list out the types of users that will use your application, based on what they can do, if they can do different things. That’s a little complex to spell out, but really easy to do. For example, if I have a medical app that connects Doctors to Patients, but the Doctors and Patients can DO different things in my app, I would start with something like this:

• As a PATIENT, I need to:
• As a DOCTOR, I need to:

That’s it! For our example app, since we only have one type of user, our persona list could be quite simple:

• As a WORKOUT APP USER, I need to:

No problem, right?

Now that we have our persona(s) defined, we need to add some high-level detail about the things that those personas need to be able to do. Let’s flesh out our example persona:

Sample Base Persona

• As a WORKOUT APP USER, I need to:
  • Download the app from the App Store
  • Download the app from Google Play
  • Get Started (Welcome)
  • Create an Account
  • See my next workout
  • Sync to my calendar
  • Start a workout
  • Perform a workout
  • Find my starting weight
  • Sign In
  • Sign Out
  • Reset my Password

Notice that we haven’t started drawing things out yet. This stage is basically a roadmap for drawing out your application wireframes. You can view it as developing a todo list for all the functionality you need to detail out while wire-framing your application.

One you feel good about your list, it’s time to get your hands dirty turning these great high-level ideas into wireframes.

Step 4: Building Wireframes

Application wireframes are probably going to be the most important requirements tool in your developers tool belt. A picture paints a thousand words, right? The same is true in software development. Nothing lets me know what you want me to build better than a good picture.

Building good wireframes can be challenging, but fortunately, there are great tools out there to help you with that. Our current favorite is Whimsical. Their wireframing feature lets you build very high quality wireframes very quickly.

The First WireFrame

To begin building your wireframes, start a new wireframe document in Whimsical, and pull up your Persona Spec.

Start with the first item in the list:

• As a WORKOUT APP USER, I need to:
  • Download the app from the App Store

Now, since downloading from the App Store and Google Play don’t technically need a wireframe (Apple and Google have that covered), we can skip to the first “real” one:

• As a WORKOUT APP USER, I need to:
  • …
  • Get Started (Welcome)

For the Get Started screen, I just want a big simple, friendly button as an intro:

I’ll add a screen label of Screen - Get Started then cross-reference that in my Persona Spec. Once I’ve added any special detail, I’ll move on to the next item in my Persona Spec:

The Second Wireframe

• As a WORKOUT APP USER, I need to:
  • …
  • Get Started (Welcome)
    • SCREEN: Screen - Get Started
      • Big, friendly button. Maybe some animated sparkles?
  • Create an Account

This will definitely need to be a screen, and it will have some inputs, like so:

Once the wireframe is complete, I’ll go back to my Persona Spec, and add in the screen reference and detail, so my persona spec looks like this:

• As a WORKOUT APP USER, I need to:
  • Download the app from the App Store
  • Download the app from Google Play
  • Get Started (Welcome)
    • SCREEN: Screen - Get Started
      • Big, friendly button. Maybe some animated sparkles?
  • Create an Account
    • SCREEN: Screen - Create Account
      • Should require name
      • Should require valid email address
      • Should require valid start date
      • Should require valid starting weight

Notice how we have added just enough detail to let developers know what they should be validating about the user input? We are giving the benefit of the doubt that they understand how to validate an email address, without taking all the time to (unnecessarily) explain validation to them. Now, if it were a custom validation (like Start Date must be in the next 30 days), we would want to add that detail as well, which is as simple as another short bullet point.

The Final Product: A Complete Software Spec in Record Time

Once you’ve made it through all of your screens, you should have a wireframe document that looks something like this:

[view it live here]

And a Persona Spec that looks something like this:

• As a WORKOUT APP USER, I need to:
  • Download the app from the App Store
  • Download the app from Google Play
  • Get Started
    • SCREEN: Get Started
      • Single, friendly button
  • Create an account
    • SCREEN: Program Details
      • Should require name
      • Should require valid email
      • Should require valid start date
      • Should require valid weight
  • See my next workout
    • SCREEN: Home Screen
  • Sync to my calendar
    • SCREEN: Home
  • Start a workout
    • SCREEN: Home
      • Clicking "Work Out" routes to "Workout Home"
  • Perform a workout
    • SCREEN: Workout Home
      • Should show workout title (A or B)
      • Should allow Machine & Freeweight Options
        • Workout A
          • Machine - Pull downs
          • Machine - Shoulder press
          • Free Weight - Yates Row
          • Free Weight - Overhead press
      • Clicking an exercise routes to "Perform Workout"
    • SCREEN: Perform workout
      • Should show exercise title & current weight to attempt
      • Should show lifting rules & cadence
      • Should require # of reps
      • Should show "Done" button
        • If I get 6 or less
          • Routes to "Stop"
        • Else
          • Routes to "Perform Workout"
      • Should show cancel button
        • Routes to "Home"
    • SCREEN: Stop
      • The purpose of this screen is stopping the workout and adding another day of rest
      • Should show the stop alert message
      • Should have "When should I workout again" button
      • Routes to "Home" with updated workout date
  • Find my starting weight
    • SCREEN: Weight Selection
      • Should show title
      • Should show "Use a weight you can do 5 times"
      • Should require lbs completed
      • Should show Next button
        • Routes to "Weight Performance"
    • SCREEN: Weight Performance
      • Should tell me how to lift (fast up, 2 seconds down)
      • Should have "I got 5" button
        • Routes to "Weight Performance" with increasing weight
      • Should have "I didn't get 5" button
      • Should route to "Weight Verification" with 70% of last successful weight
    • SCREEN: Weight Verification
      • Should show starting weight
      • Should have "Ok" button
        • Routes to "Perform Workout" for that exercise

Woohoo! You now have a complete Persona Spec, ready to hand to developers! Your spec should include, in this order:

• Elevator Pitch
• User Stories
• Persona Details
• Wireframes

view a full example of (dated) deliverable here

If you have done your job well, any seasoned developer should be able to begin productive work on your application with nothing more than these resources. You did it!

Step 5: Adding Polish (optional)

At this point, and before you engage a developer, you may want to hire a designer to add some really nice polish to your User Interface, and that’s totally acceptable.

If you decide to go this route, I would recommend giving your developer the design Finals from whatever designer or design service you engage. This will add the styling expectations to your spec, and make your life, and your developers lives even easier.

Conclusion

This may seem like a lot of work, but believe it or not, this exact spec, including the Elevator Pitch, User Stories, Base Persona Spec, Wireframes, and adding detail only took 1 hour and 45 minutes to complete, from start to finish.

We know, because this spec was one of our early experiments trialing this out, so we actually timed each of the stages, and costs. In the end, here were the stats:

see the final designs

Using the Persona Spec method, you can quickly build a spec that is as flexible, cheap, and fun as the Whiteboard method, but with enough detail to compete with the Waterfall method for completeness.

And when compared to the months invested in true Waterfall style requirements gathering, along with the level of detail and instant understanding developers will have about the app, having a spec this complete in less than one day should be considered a HUGE win that you can replicate over and over again.

Subscribe to 🎉💪 content!

Get our tech articles once a week, free of spam.

Subscribe