Contextual Business Concepts
How do you explain a large complex system that is under constant rework to pursue an evolving business reality?
Founded in 2007 by José Neves for the love of fashion, and launched in 2008, FARFETCH began as an e-commerce marketplace for luxury boutiques worldwide. The marketplace became the leading global platform for the luxury fashion industry, connecting creators, curators, and consumers.
As you might expect in a company overgrowing, different teams struggle to build different systems and evolve different parts of the business, using different skills, often while training junior team members. These teams develop and evolve their own mental models. Over time, models from different teams become subtly incompatible with each other, leading to inconsistencies in products and processes. The largest inconsistencies appear between business and technical people and between different technical teams. And thus, we reach the situation where describing the whole business at an adequate level of detail in a way that everyone at FARFETCH may use, is no longer a trivial endeavour.
The challenge is to propose a systematic business description that is useful to the different teams and that can be maintained collaboratively.
What has FARFETCH tried before?
The Technical Writing team initially used business comics to introduce business processes. The comics had an impact internally but failed to explain the whole business. Ensuring completeness and capturing a consistent level of detail proved hard.
Drawing inspiration from Domain-Driven Design, the Technical Writing team has been abstracting away technical detail from API concepts to create business-level concepts. The approach has been useful to identify insightful tutorials, enabling better conversations with technical and business experts and supporting discovery and navigation in the developers’ portal. However, ensuring completeness and capturing a consistent level of detail is still hard.
Other teams have been tackling parts of the same problem from different vantage points. For example:
Data Architecture has been creating conceptual and logical models of data in databases.
Data Governance has been identifying and defining business terminology.
Architecture has been creating reference architectures that describe FARFETCH systems and justify their purpose.
Product has been classifying functionality into products and features.
Part 1: Business context
The inspiration for the current approach came from the contextual diagrams in reference architectures. These diagrams treat the system being described as a black box and focus on describing how the system interacts with people and with other systems. We build upon that practice by ensuring that the interactions include all the actors (people and organisations) affected by the system, not just interactions with nearby systems.
Chunking the business into areas
The first challenge is to chunk the business into areas that address a specific business concern. Several actors interact in a good business area to address a business concern.
A good business area archetype emerged from a quiet conversation with Adão Teixeira, one of the first FARFETCH employees. The role of Adão in 2017 was to ensure that boutiques selling through FARFETCH had an adequate stock of branded boxes to ship their luxury products. This required managing deliveries from local box suppliers into the limited storage space at each boutique while anticipating the number of boxes of each size needed to fulfil sales.
Identifying actors
Actors directly concerned with a business area are normally easy to enumerate. For example, authors and readers of a developers’ portal.Actors concerned with the same business area, but interacting with other parts of the system can be harder to identify. For example, partner managers that decide who can become a reader by interacting with a centralised authorisation system.
Enumerating a business area’s actors (people and organisations) is usually an iterative process. The business context becomes more useful when it goes beyond the obvious and captures the business concerns of more actors.
Capturing interactions and motivations
To complete the description of the business context, we describe the meaningful interactions of actors with the business area, without getting bogged down with irrelevant detail. It is usually enough to express the roles of each actor. For example, a staff member manages the access of partners to documentation.
Crucially, we also express the benefits that each actor gets from their interactions with the system. For example, the same staff member has a centralised view of all partner authorisations. These benefits are the motivation for the actors to participate in the business area. Knowing the motivations also makes technical communicators stronger advocates for the needs of the actors.
The business context becomes more useful when the motivations go beyond the obvious. For example, if a person does something because ‘the boss tells him to’, we should probably reconsider that person as an agent for the real actor. So, perhaps the actor in the business context should become the organisation where the person works.
Presenting the business context
Currently we present the business context with the following parts, as shown in figure 1:
A diagram that shows all the actors and their interactions with the business area.
A description of each actor.
A description of each interaction, including the motivation or benefit for the interaction to exist.
Since the business context describes the actions of people, business comics can quickly convey to readers the essence of a business area.
Part 2: Business domain model
The business context described the motivations and interactions of actors. Now we focus on what actors see during the interactions.
Identifying concepts
The business area mediates the exchange of physical items or information items among actors. For example, in the business area of Adão Teixeira, branded boxes are physical items, and orders to restock branded boxes are information items.
Sometimes, we must choose the adequate level of abstraction to identify and describe the items. For example, a Markdown file written by an author may originate the concepts Markdown, topic, or authoring format. The business domain model may include one or more concepts for each item. However, the model should only include the concepts perceived by the actors, omitting both implementation details and useless abstractions.
Describing relationships
Describing the relationships between concepts moves the description away from a simple glossary and towards a mental model of the business area as seen by the actors.
For example, DITA and Markdown are authoring formats, and topics in an authoring format are transformed to PDF.
Currently we present the business domain model with the following parts, as shown in figure 2:
A diagram (domain model) that includes all the concepts visible to the actors while interacting with the business area and the relationships between the concepts.
A description of each concept and the relationships between them.
We augmented the descriptions of concepts with their relationships, but we wonder if some relationships might be better described separately from the concepts.
Practice with previous concepts at FARFETCH suggests that there is an urge to refine models and descriptions every time the concepts are discussed in a meeting, with a corresponding difficulty to decide what should be in each model. The contextual point of view helps decide what should and should not be in the concept and sets limits to the levels of abstraction and detail.
The goal is to describe the business systematically, as a coordinated set of business areas that can be kept up-to-date effectively, to support the onboarding of people and organisations, to enable the evolution of ideas, and to foster alignment across business and technology.
This article was originally published in ISTC Communicator, Summer 2023.
References
Eric Evans (2003) ‘Domain-Driven Design: Tackling the complexity in the heart of software’ Addison-Wesley
Joaquim Baptista (2019) ‘Inspire with comics’ Communicator, Winter 2019: 28-31
Joaquim Baptista (2019) ‘Domain models for technical writing’ TCeurope Colloquium, Porto
