Delivering Results with Requirements Engineering, Part II – The Functional Specifications Document

EDITOR’S NOTE: This blog post is the second in a continuing series about the importance of a requirements engineering process. If you’re considering an eCommerce project at your company, you’ll want to watch this space. The posts in this series will help explain how having a solid process in place saves time, work, and money. It also turns clients into partners and when that happens, everybody wins. Enjoy this post, and be sure to stay tuned for the rest of the series.

In the first blog post of this series, we introduced you to the concept of requirements engineering and the process that ten24 has created. Among other things, we provided an overview of the steps the process involves, explained its benefits, and mentioned the four key deliverables that should come out of the process. This post is going to focus specifically on one of those deliverables: the functional specifications document (or FSD, for short).

In the overview, we mentioned that a hallmark of an effective requirements engineering process is a substantial “middle ground” where a lot of back-and-forth work takes place between the service provider and the client. Here’s another look at ten24’s requirements engineering schematic, which shows how it all happens.

You’ll see that in Step 2 of the process, there’s significant time spent in discovery with the client. This is where the provider gathers all of the information required to start the project. Eventually, after a client reviews and accepts the statement of work that’s presented (Steps 3 and 4), it’s time to focus on the FSD.

The beauty of this document is that it captures all early-stage discovery in one place while still providing the flexibility to accommodate and manage change as a client’s project progresses. To say that the FSD is important is an understatement: It’s the bible, or single source of truth, that everyone who’s involved in the project will refer to from development kickoff until implementation and beyond. It’s a pretty big deal.

So what does a typical FSD look like? Well, it should begin with a project summary, which features a brief, high-level description of the client’s project (much like an executive summary). Then comes a bullet list of the key objectives, which identify exactly what the project should accomplish. The next thing you’ll want to see in the FSD is the project scope, which names the key components of the project, along with a description of each component.

Because the FSD is the bible that everyone consults during the lifecycle of an eCommerce project, it’s especially useful in helping to avoid the dreaded “scope creep” – something that can completely derail a project. Remember the cake-baking analogy we used in the first post of this series, where we likened the requirements engineering process to a recipe? The analogy works equally well with scope creep.

Let’s say you run a bakery. A customer calls you and places an order for a simple sheet cake with buttercream frosting. Easy, right? Not so fast. Soon, things go haywire: Your customer calls back three separate times over the next day and keeps changing the order. First, he asks for multiple layers instead of a sheet cake. Then he announces he wants a different flavor of filling in each layer. In his third phone call to you, he throws in a request for candied rose petals on the top layer. You can accommodate those requests, of course, but that kind of cake is going to be way more expensive than the one the customer originally ordered, and it’ll take you much longer to make it. What you’re now being asked to bake is about as far from a sheet cake as you can get. That’s scope creep.

Any “extra” that gets added to the project scope has the potential to impact the project’s timeline and budget. As discovery with a client continues (Step 5), a service provider should be constantly checking and double-checking the project scope, reviewing it with the client, and asking the client to confirm whether something should (or shouldn’t) be part of the scope. All of this is recorded and agreed to in the FSD, so that scope creep doesn’t become an issue.

With the project scope nailed down, now it’s time to address the system requirements section of the FSD. The exact requirements and specifications will vary according to each client’s needs, but common system requirements may include reports (e.g., how they’ll be configured and generated), benchmarks (e.g., certain performance standards that the client wants to hit), and permissions (e.g., setting limits on what system users can see and what they’re able to do). The FSD will also list user roles, which specify what certain users (e.g., admin user, end-user, etc.), have access to. User roles also provide an overview of what those people will be using the site for.

From there, it’s on to writing user stories, which explain and describe extremely visible system behavior. Anything that someone can do as a user of a system is considered a user story. It’s critically important to identify and list these stories in the FSD because they are turned into tasks that the developers use to build the actual project. Writing the stories follows a distinct format that goes like this:

“As a _______, I can _________, so that __________”. For example, a user story for someone who is an administrative assistant in a sales department might read, “As an admin user, I can filter a report by time period so that I can see sales results for 1-, 7-, 14-, or 30-day time periods.”

As we mentioned earlier, user stories do much more than keep a project organized. They capture context for the developers who are building a client’s system. That’s because the stories put developers in the shoes of the user. Instead of being told to “build this widget,” developers understand what users need to accomplish. But this also benefits users. Instead of technical mumbo-jumbo, users get to see actual pieces of functionality, written in plain English.

The user stories section of the FSD should also contain the acceptance criteria and testing notes for each piece of system functionality that a particular user story represents. This is helpful for the service provider’s Quality Assurance team, who will test all functionality before it goes to the client (who will, in turn, also test it).

The more complex a client project is, the bigger the FSD will be. With extremely large projects, user stories should be broken into multiple, smaller chunks so that developers can work on and deliver them in batches in order to keep the overall process moving along smoothly.

An added benefit of the FSD is that it becomes invaluable when it’s time to generate user manuals for the systems that are being built. When the FSD has been done properly, the client’s system will be so well documented that the service provider should be able to copy and paste large amounts of content from the FSD into the appropriate sections of the user manual (particularly the information that the user stories contain).

But we’re getting a little ahead of ourselves by talking about a user manual for a system that hasn’t even been built yet! So, how do you know when that FSD of yours is “done”? That can be a little bit of a balancing act. Ideally, service providers are looking for the point where they can say, “OK – we’ve collected enough information and input that we’re ready to start developing.” You want to avoid analysis paralysis (where you’re overloaded with too much data), yet you don’t want to have gaping holes either. When you’re making only minimal tweaks to the FSD, it’s a good indication that you’re done.

In the third post of this blog series, we’ll tackle another deliverable in the requirements engineering process that is usually created in tandem with the FSD: wireframes. Stay tuned!