The functional representation flow. A way to reconcile Product Management, Product Design, and Development.
In the tech industry, building a feature usually involves many processes and people, including Product Management teams, Product Design teams, or Development teams.
This is why teams write functional requirements.
These functional requirements are a big deal: they have a significant impact on those same processes and people. And its impact is generally underestimated.
Additionally, the way functional requirements are represented varies from domain to domain. And this hurts the overall building process.
To streamline this process, we propose a new functional requirements flow that turns a bunch of boring tasks into a fantastic facilitator tool.
A classical feature building process
This is a very simplified picture of the different processes and work involved. Each process generates its own artifacts.
Artifact (software development), noun, one of many kinds of tangible by-products produced during the development of software.
Each organization has its processes and artifacts. Obviously, this is a linear workflow. In reality, there could be many interconnected steps within each step of this workflow. We’ve simplified it to make it easier to understand.
We’re going to focus on the functional requirements stream and the transformations commonly required by each discipline, especially the transitions and the artifacts involved.
A classical functional requirements journey
From user and stakeholders to requirements
The requirement engineering process starts by collecting needs from a user and/or stakeholders then transforming them into requirements.
Generally, it’s an initial specification document with data, text, bullet points, diagrams, or other clarifications.
From requirements to mockups
The product design process focuses on analyzing and supplementing these requirements via user interviews…, user scenarios, data hierarchy, user flow, wires, user tests, etc. At the end of the process, these requirements are transformed into mockups.
From requirements and designs to user stories and tasks
Within the task management process, user stories or tasks are created. These describe what the developer has to do by breaking their work up into smaller tasks. These can be supplemented with technical specifications.
From user stories and tasks to code
The development process will take a user story or a task, and transform it into code.
From code to acceptance tests
The quality process will aggregate all the different requirements and will transform them into tests.
Transformation Hell
Too many transformations
From user needs to the final result, the whole process went through a series of 6 transformations.
Since each process produces its own additional transformations, we could count far more than that.
Differents representations
Actors of the processes are not using the same functional requirements representation, they generate their owns.
Product designers will write user scenarios based on requirements. From there, they’ll build prototypes that will be transformed into mockups and much more.
Developers need to fit or transform these requirements into a required or existing architecture.
Coupling
Processes are tied closely together. Each artifact generated is needed to produce the next one. These makes the processes interdependent — or tightly coupled — and makes it more complicated to streamline.
Requirements for applications are what change most often. Even the smallest of changes will have to go through all of the steps in the process.
This leads not only to user needs being distorted but to a lot of wasted time.
How did we end up in this situation?
Every field has its own way of working, its own methodology, and even if there is some collaboration in operational factors, real collaboration on methodology is rare. Also, education has a big role; product managers, developers, designers are all taught how to do requirements differently, based on the specific needs of their role, rather than with a global perspective.
The functional representation flow
Flow, verb [ intransitive ]: To move smoothly and continuously.
Flow (psychology), noun: A mental state characterized by concentration, focus, and enjoyment of a given task.
The flow of the functional requirements should be based on a common shared representation. This common optimized representation should be used in all processes. Each process should work on reducing transformations they have to go through.
A common shared representation and few transformations.
A common shared representation
A common language
Ubiquitous language
Ubiquitous language is the practice of building a common, rigorous language between all the people involved in a system. This includes domain experts, Product Designers, engineers.
Ubiquitous language helps communication between these various stakeholders. Definitions can and should evolve as the team’s understanding of the domain grows.
Modeling language
Functional requirements can be hard to model, especially for large and complex systems. You have to start from a macro perspective down to the most precise detail, including workflows, states, dependencies. While text is important, it’s generally not sufficient or appropriate for this task.
UML, meanwhile, is actually designed for this kind of work. It provides tools and methodologies to model large and complex systems, all from a functional perspective. It provides a common language, with common references and format.
UML originated along with a methodology, Unified Process, which is not always well known. Unified Process details the steps and the techniques required to model a functionality.
Unified Processes doesn’t need to be used “as is,” but some of its principles should be applied.
The representation
Based on needs, the goal is to define and model the actors of the system, their intentions, actions, details of their actions and dependencies; entities with their data, states, actions, and relationships.
The use case model
The use case diagram is a model containing actors, use-cases, and their relationships. This model focuses on describing what the system should do for its users and under what constraints. It also addresses the static use case view of a system.
The Unified Software Development Process, Ivar Jacobson, Grady Booch, James Rumbaugh
Activities diagram (optional)
A diagram that shows the flow from activity to activity; activity diagrams address the dynamic view of a system.
The Unified Software Development Process, Ivar Jacobson, Grady Booch, James Rumbaugh
The domain model
A domain is an area of knowledge or activity characterized by a set of concepts and terminology understood by practitioners of this area. A domain model is an object model of the domain that incorporates both behavior and data.
Pattern Of Enterprise Application Architecture, Martin Fowler
The domain model represents the entities of the business (for example a user, a product, a category…), their data and their relationships.
State diagram (optional)
A diagram that shows the behaviors that specifies the sequences of states an object goes through during its lifetime in response to events, together with its responses to those events; state diagrams address the dynamic view of a system.
The Unified Software Development Process, Ivar Jacobson, Grady Booch, James Rumbaugh
These diagrams should define the base of the functional representation and should be supplemented by all other relevant information of different kind.
Fewer transformations
From user needs to a common functional representation
The requirement engineering process can be reduced to collecting the needs from a user and/or stakeholders and transforming them into Use Cases and Domain model. It could be supplemented by activity diagrams, state diagrams, text descriptions or anything that could give useful information. All together, they form the functional representation.
From the functional representation to design
The Product Design process will use the functional representation as an input for the process. The Use Case diagram helps to define the scope and user scenarios.
An activity diagram is a start for user flows.
A domain model is the base of the information organization and data hierarchy. Used at the start of the OOUX methodology, it will help define UX components.
State diagram and other diagrams or information will help the process too.
The Product Design process will supplement and update the functional representation with use cases, activities, entities, states discovered or used during the process.
From the functional representation to tasks management
The task management process will transform use-cases to tasks: one task per Use Case. Additional tasks and user stories will be written to cover the other small behaviors or work needed by the system.
From the functional representation to development
The development process will transform functional representation to code. The domain model provides the entity definitions. Transformations could be optimized by the usage of the right architecture. Domain Driven Design fits well for a smooth transformation of the Domain model. Clean Architecture will improve the transformation of use cases as they are used similarly to what’s applied in the application.
From the functional representation to quality
The quality process will transform the functional representation to tests. BDD or other behavior based test will be easily written.
The benefits
This flow introduces one common representation (composed of Use Case model, Domain Model, activity diagrams or state diagrams, and all the other relevant information), shared by all the people and the processes and reduces significantly the transformations.
It introduces also one transformation from the need to functional representation, and in the best scenario, one from functional representation to the process deliverable.
Quality
By having always one transformation from user needs to functional representation, it ensures that every process is close to reality, and fits the needs.
Because this representation is shared by every process, it is also nurtured by every process. Improvement and updates benefit everyone.
Errors
Less transformation leads to fewer potential errors or misunderstandings. The shared representation avoids coupling. If a process fails, the other process may not be impacted.
Efficiency
The common shared representation avoids having to repeat multiple steps in a long process.
Furthermore, fewer transformations in every process avoid wasting time
And by reducing complexity, it makes it easier to automate like generated code for example.
Flexibility
Because common shared representations lead to low coupling, changes apply easily. Each process does not always need the previous one to work on the changes.
Where should a team start?
To be successful, the team must understand, communicate and commit to these principles.
Start learning the basics of UML and how to use it to model a functional representation, define ubiquitous language (via a glossary for example), and create a single source of truth.
Then analyze the impact on every process, adapt it, practice and adjust. And start again.
Resources
Requirements engineering
Ubiquitous language and domain model
Domain Driven Design, Eric J. Evans
Ubiquitous Language, Martin Fowler, https://martinfowler.com/bliki/UbiquitousLanguage.html
Pattern Of Enterprise Application Architecture, Martin Fowler
UML and Unified Process
The Unified Modeling Language User Guide, Grady Booch, James Rumbaugh, Ivar Jacobson
The Unified Modeling Language Reference Manual, Grady Booch, James Rumbaugh, Ivar Jacobson
The Unified Software Development Process, Ivar Jacobson, Grady Booch, James Rumbaugh
Applying UML and Patterns: An Introduction to Object-Oriented Analysis and Design and Iterative Development, Craig Larman
Map Out Your Project With UML, Emily Reese, https://openclassrooms.com/en/courses/4300566-map-out-your-project-with-uml
Use cases and stories
Use Cases and Stories, https://martinfowler.com/bliki/UseCasesAndStories.html, Martin Fowler
Use case, https://martinfowler.com/bliki/UseCase.html, Martin Fowler
User Story, https://martinfowler.com/bliki/UserStory.html, Martin Fowler
User Stories Applied, Mike Cohn
Writing effective use cases, Alistair Cockburn
Product Design
UML and UX
Applying Lessons from UML to UX, https://www.uxmatters.com/mt/archives/2010/11/applying-lessons-from-uml-to-ux.php, Peter Hornsby
UXML: a designer’s new best friend, https://uxdesign.cc/uxml-a-designers-new-best-friend-de12f2fffbeb, Florian /flɔ.ʁjɑ̃/
OOUX
OOUX, https://www.rewiredux.com/ooux, Sophia V. Prater
Engineering
Domain Driven Design, Eric J. Evans
Clean Architecture: A Craftsman’s Guide to Software Structure and Design, Robert C. Martin
