How do you get better business requirements?

by | Oct 3, 2022 | Blog, Dev Team

I’m sure that this is a familiar and ongoing issue for many organizations.

We sit our business users down with our developers and/or business analysts to outline the business requirements for our application. Something gets written down, the developers take it away and code it up, bring it back for user acceptance review and…

  • You didn’t understand what we asked for
  • This is what we said but it isn’t what we meant
  • Looking that this, it would be better if…
  • Can we just change this…
  • It’s what we wanted then, but the need has changed

In most applications, the vast majority of our business requirements are focused on the user experience. For example, “we need an Order form with these fields… but if it’s in the Submitted state then these extra fields are needed, but these fields will become read only, unless you are a manager and then we also need these extra mandatory fields…”

As business analysts, we try to capture all of this information in a set of wireframes with attached notes showing how the wireframe will change depending upon state, user role, or custom business rules. This documentation is passed to developers who make their best guess as to what the application is supposed to do in each of these situations and they take anything from a few days, weeks, or months to come back with a working application. Then we document the required changes in the user acceptance review and rinse repeat.

When you pull apart the final application, the custom pages that render the user experience will constitute around 95% of the total code written to maintain the database data. The remainder (often around 5%) is automation or workflow code to address requirements, such as: “how do you calculate the sales tax on the order?”

We can mitigate some of the effort required to build the user experience with various code generation technologies, but we are still coding pages in our application that will need to be customized and maintained over time. Code generation gets you started faster but you still have code to customize, test, and maintain.

A better alternative?

Why not create the user experience as a data model that can be rendered by the application at runtime?

The basic idea is that you can model in configuration data a description of what the user experience needs to do at runtime. For example, if we are displaying an Order form, we can use configuration data to determine which tabs/fields should be displayed depending on the state of the Order or the roles of the user.

In practice, you need to model surprisingly few things to create a user experience form definition.

A Tab can either be displayed or hidden. We can determine which depending upon:

  • The state of the object
  • The roles of the user
  • The type of device and its orientation
  • Any other special business rule

A Field on a Tab may be hidden or displayed. If it will be displayed, then it may be editable or read-only. And it may be mandatory to fill in or optional. The view state of the field will also depend upon:

  • The state of the object
  • The roles of the user
  • The type of device and its orientation
  • Any other business rule

The trick is to create a dynamic page builder that can combine the record that will be displayed and the roles of the user who will see the form with a form definition.

How does this improve our requirements?

From our experiences with our trellispark platform, we’ve found that with an easy-to-use dynamic page builder, you can create the actual user experience with extraordinary speed. In fact, most of the user experience can be configured during the requirements meeting with the business users and business analysts. You don’t need to document the requirements – you can literally just build it!

It takes a few seconds to add/update field definitions which is a small fraction of the time typically taken to discuss whether the fields are correct when trying to add them to a wireframe.

The business users can immediately see what the application will do depending upon the object state and different user roles.

It’s easy to quickly try out alternative field layouts and options to optimize a user experience that best fits their needs.

Once they reach consensus, the user experience is done.

What about the automation requirements?

There will likely be some automation/workflow requirements outstanding once all the form definitions and fields are done.

In most cases, these will be directly related to the user experience. For example, “If a user can see this button, then when they click it, this happens… If a record changes state, then this happens…” The fact that most of the user experience has been defined, means that we don’t need to discuss the user context of this automation anymore. The button is either clickable, or not.

This means that the requirements for the workflow are now smaller, more precise, easier to document and test. The developer has a better chance of correctly implementing the workflow as requested and if they do make a mistake, it is faster to identify and correct.


Modeling the user experience in data rather than writing code significantly reduces time to market, effort, and risk when building complex applications.