No one reads requirement documents, but we can change that.

Justin Brodeur / August 6, 2018

Picture this: You have an idea for an app that you know will help your company save money, win greater market share, or create new efficiencies. You pitch the idea to your manager. They sit, nodding their head in the general direction of each of your points, but their glazed-over expression and other non-verbal cues communicate their truth – they have no idea what the heck you’re talking about.

Enter the functional requirement specification (funcspec).

A funcspec is a document that specifies the functions that a system or component must perform. The goal of the document is to hit that sweet spot in defining what a user needs, so that a group of nerds can translate those needs into amazing (working) software.

Think of the funcspec as a movie script. Like any flick, if the plot is boring, people will tune out and turn their attention somewhere else. I can’t tell you the number of times I’ve had to review bad requirements documents full of acronyms and robotic language. Even the most well-intentioned person will undoubtedly stop reading the document two pages in.

We can combat reader fatigue by creating funcspec documents that are easier to read. The idea is simple – write in plain language, add color and humor to the document, and vividly paint a picture of who the users are, what they need, and how your gajillion-dollar idea will make their lives better.

Beyond the language and tone used, every funcspec can be broken down into some very specific ideas and components.

There is only one author

Have you ever seen something designed by committee? We have. Everyone pulls in their own direction, decisions don’t get made, and the results either suck or are non-existent. By giving ownership of the document to one author, you empower that person to be ruthless and cut the shit; they’ve got the ownership and, as such, take the responsibility for a clear-cut document.

The document is a living, breathing, evolving thing

The document will change. It needs to change. We also need to let people know that it’s going to change (that happens in The Overview). In fact, as this is 2018 (and beyond), we go chasing Waterfalls. We develop in an Agile workflow. We’ll build something, it will suck in some unforeseen way, and we’ll have to rethink and rebuild it. The document needs to reflect that.

The Overview

This is where we give a short blurb about what the project is and what we hope to accomplish. We make it absolutely clear that this document is not, I repeat not, complete. The document will change, and we don’t want to get people all worked up about it. Instead, we let them know that change is expected, and change is good. We also let them know that the graphics and layouts of the screens are there just to illustrate the underlying functionality, and they shouldn’t be picked apart by a creative director who smokes Parliaments and wears a beret.

Scenarios

This is where we present actual scenarios that stereotypical people would come into contact with. This is where we get to have some fun. We can talk about Elijah, the new employee who isn’t financially literate, but who wants to move out of his frat house-style apartment and get a place of his own, and how our financial wellness software will help him do that.

Non-Goals

This is where we get to express the things that we don’t want to deal with in this iteration. It could be things that are super scope-creepy, or things that we’re not willing to do on day one. Not to say that they can’t be accomplished down the road in another release, but this is the stuff that we just aren’t going to tackle on this go-around. If people know where no is, they can focus on the things that we’re saying yes to.

Flowchart

A picture is worth a thousand words. This can be a crude rendering of how the software works, or a user flow. Pretty much anything that makes it easier for someone to take a glance and be like, “Oh yeah, the user needs to log in before we expose them to our amazing gizmo-thing-a-ma-bob.”

Screen-by-Screen Specification

This is the most important part, because this is where we get into the nitty gritty detail of each screen. We describe, in outrageous detail, the layout of the screen, inputs, outputs, and what happens for every possible scenario. Each screen represents a number of decisions that someone has to make, and which the author needs to document. For instance, what happens when a user enters a fake email address into an email input? Do they see an error message? What does that error message say? How do they get rid of the error message and right their inputted wrong?

Open Issues

On each screen we leave a slot for open issues. These are bits of info like, “Figure out the copy for the error message, because we can’t just say ‘you screwed up.’” They don’t need to be resolved today, but we need to make people aware of them and at some point get to a resolved state.

Technical Notes

These are little love notes for the engineers. They can be things like, “Do we want to use Ajax here?,” or, “Maybe we should think about a paid alternative to Google Maps.” It could be anything technical or towards the business of being technical.

Tying it all together

By building a document that vividly describes every component of your application in excruciating detail, and by using humor to bring some levity, we can create something that people actually don’t mind reading. In effect, we’ve hacked their idea of what a technical specification is, and we’ve made it so that they actually want to read the thing and don’t pull out their phone two pages in to see who the Celtics just traded for.

We’ve had such good success with our funcspec documents that we use them as a selling tool. As part of our process in getting to know a prospective client, we hold regular phone calls where we learn about a given problem and what their hopes and dreams are when it comes to solving that problem. The result is a complete funcspec document that they can use as a blueprint to build a solution. We want to build value for them, and we love solving a good problem.

If you want to learn more about our approach to funcspec document writing, or if you have a problem that you’re itching to solve – give us a shout.

Arrow Icon explore more of our thinking

No one reads requirement documents, but we can change that.

read more

Nine Secrets to App Store Optimization

read more

Make onboarding a positive user experience

read more