All the Code We Cannot See: Accounting For Non-Interface Requirements in Software Development

When you work on web and mobile applications, often the hardest part of getting everything right is making sure you account for all the things that can’t be seen.

At WillowTree (formerly Dynamit), we preach interface-driven development (IDD). It’s our system of organizing information around interfaces. We’ve used IDD for everything from scoping to requirements gathering to scheduling to QA. But the name interface-driven development implies something. It implies that everything has an interface. And that’s true, if you were writing code for something that would never end up in an interface, or perhaps more accurately never be interacted with, well… then it would just be code for code’s sake. But, there are lots of things that go into an interface that will never be seen. These are the non-interface requirements.

They may not be as pretty as the interfaces they support, but often they are the most important, most critical requirements of a project. The importance of getting them right and documenting them can’t be overstated.

What Are Non-Interface Requirements?

First, let’s say what they aren’t. They are not the requirements that define user experience. They also are not requirements for the newly invented term “interfaceless design.”

Simply put, they are the things that happen behind the scenes. The things IT cares a whole lot about.

We think about non-interface requirements in three main buckets:

1. Non-functional / devops requirements. This first category includes many of the things that will dictate how an application is architected. At this point, we are simply listing all of the things that go into the site, not directly spelling out how they will be used. This includes:

  • The languages used for a site
  • The frameworks used for a site
  • Integrations needed for a site
  • What devices will be involved
  • How we’ll support an application
  • Versions of languages and frameworks we’ll use
  • Hosting requirements
  • Server architecture
  • The app’s Operating Platform Model (OPM)

2. Web Services. The second category includes all of the services and APIs needed to make an application fully functional. This is the category that gets us to where we are going to be pulling data for the application and how we’ll integrate third party tools. These might be listed in category one, but the details of how they get used are spelled out in category two.

3. User Acceptance Criteria. This last category is the one most closely tied to the final solution. This category of requirements details what is and isn’t a success for an application. These requirements are often tied to an interface, but don’t define the interface. User requirements are great for defining what an experience should be, but you need the business logic and user acceptance criteria to be able to build an application successfully.

How to Document These Things

Knowing what to document is half the battle. Knowing how to document is a challenge that has caused many a sleepless nights throughout the digital agency world. We, as an industry, have a problem. We want to make sure everyone knows everything they need to know. We also want to make documentation easy to read and understand. We also want to make documentation that works for marketing and IT teams. Succeeding on all of these fronts is hugely important for project success. But this is a challenge without a single solution. There’s no magic bullet. The best way to document non-interface requirements really depends on the project and the client. You have to consider your audience and their needs.

The WillowTree Way

While there’s no one-size-fits-all solution, there are some things you can think about to help you make the right “how to document” decision.

1. Is IT involved in the project OR will they need to support the app long term?

If the answer is no to both, then you need to document for your internal team only. This means you get to pick the format, but (likely) won’t need to include many technical details in client documentation. This will just overwhelm your client and could cause them to miss the important things they need to see in your documentation. The documentation you prepare for your internal team is still very important and should be as well done as if it were being passed to a client’s IT team.

2. Assuming IT is involved, are they leading the project or joining?

If they are joining and not leading, you are likely okay with separate documentation for interface and non-interface requirements. They’ll want the technical details that are needed to support an application long term, and want to know that you’ve got the right solution in place. But if they aren’t the only stakeholder in play, you are likely better off with separate documents. We use a Technical Specification Document (TSD) to capture all of our non-interface requirements in a stand-alone document. This works really well when the level of involvement of IT is to maintain the solution and check the boxes, rather than to drive functional decisions.

3. Is IT your only stakeholder?

This one is easy. If IT is your only stakeholder, you may as well include all of your requirements — both interface and non-interface — in one document. This creates a single source of truth and all of the requirements will be meaningful and understandable for your audience.

What Really Matters?

The exercise above is all about figuring out who your audience is and what will be relevant to them. We don’t want to overwhelm our audience with details they don’t need or want. But, we also don’t want to have too many sources of truth. We need a variety of solutions because we serve a variety of clients. Finding the right mix means understanding your client and delivering the solution that meets their needs and only their needs.

How To Do It Well

Now we’ve told you what to document and given you ideas for how to document non-interface requirements. But the question remains, how do you do it right? How do you make sure you’ve hit everything? This is where collaboration comes into play. You need both UX and tech at the table. We use our architecture team to create UX requirements and have our tech teams poke holes in those requirements before they ever make it to a client’s hands. We have our tech teams involved more heavily than most agencies so that we can make sure the solutions we propose are as technically sound as they are aesthetically beautiful. You have to have a team with programming knowledge included in the discussion. You have to have people who know how to break an application and who have broken applications and come out on the other side. There’s no substitute for experience.

For more on the other half of this equation, check out “The Secret Sauce: Interface-Driven Development.”