Design thinking, domain storytelling and API design

Guest contribution by | 04.04.2024

How seemingly separate approaches can work together

Design thinking and domain storytelling are methods that can be used to design and model complex systems today. Design thinking is a method for generating new, unconventional ideas. Domain storytelling is a method for modelling software in a simple and targeted way. APIs are interfaces for software programmes. Apparently, these three things have nothing to do with each other. Or maybe they do – that’s what this article is about.

Generating new ideas – design thinking

Let’s imagine we want to redefine an entire industry with a product or software. Just like Netflix has done with its streaming service or AirBnB with its overnight stays. To come up with such new ideas, it’s not enough to simply continue thinking along familiar lines. No, you have to say goodbye to the familiar completely. Nor is it enough to ask your users what they want, because they can’t easily free themselves from their habits either.

If I had asked people what they wanted, they would have said: faster horses – Henry Ford

Even if the quote is only attributed to Ford, it expresses something crucial; only improving an existing product will not satisfy the crucial needs of users. This is where new ideas are needed.

Design thinking is a method that helps to develop and test such new ideas. Design thinking is a systematic approach to complex problems from all areas of life. The approach goes far beyond traditional design disciplines such as shaping and design (Hasso Plattner Institute, 2023).

According to the design thinking approach, innovation develops from benefits for people, technological feasibility and marketability. The process is characterised by iterative loops in which a team moves from the problem space to the solution space (Hasso Plattner Institute, 2023).

Design thinking process

Figure 1: Design thinking process according to (Hasso-Plattner-Insitut, 2023)

In the first steps of the process Understand, observe, define point of view, the team tries to understand the user’s problem. This can be done, for example, by developing personas. From a defined point of view from the problem space, the solution space is opened up and ideas are found. In the first step, there are no limits to the imagination.

Let’s imagine an IT consultant who is always struggling to develop offers for customers. No one ever has time to look at the problems and wishes of potential customers and create detailed offers. Either the quotes are too expensive – because too high a risk premium has been selected. Or the contract is awarded, but the price does not cover the costs. The head of the company does not realise which is worse in this case.

He commissions a team of various specialists to find a solution to the dilemma. The team develops various personas for which a solution is to be developed:

The client Will Whiteman

Will is 66 years old and is the managing director of a mechanical engineering company. He is an old hand in mechanical engineering and knows his way around the industry both nationally and internationally. He knows that he needs to expand his products to include digital products in order to survive on the market. So he places an order with an IT service provider for such a product extension with a digital twin, a maintenance forecast and automatic ordering of consumables.

The contractor Mary Smart

Mary is 39 years old and studied computer science. Immediately after graduating, she worked in a large consultancy firm. After the birth of her son, she set up her own business because she wanted to be able to spend her time more freely. She was so successful that she now runs an IT consultancy firm with almost 50 employees.

The developer George Millner

George is a developer and works for Mary’s IT consultancy firm. He studied computer science with moderate success. He likes to develop for himself and has no desire to be tied down to estimates. He is repeatedly called to his boss because offers are either too expensive or don’t cover costs. He has vowed not to give an estimate for the next quotation.

With these three personas in mind, the team develops ideas. Many ideas are immediately discarded by the team – some look too utopian, some already exist and others would require changes to the legal situation. But one idea seems lucrative to pursue further. The team draws up an idea sketch for this idea.

Idea sketch for an automatic quotation generator

Figure 2: Idea sketch for an automatic quotation generator

The team presents the idea sketch to the management. The management is impressed by the result and instructs the team to develop prototypes for the idea.

Domain Storytelling

In order to develop and test a prototype, the team decides to carry out domain storytelling for the offer generator. They invite colleagues from Development and Management to take on the roles of Mary Smart and George Millner respectively.

The team organises a workshop in which participants can take on the role of experts. One team member takes on the role of moderator and visualises the experts’ story.

Domain storytelling is a workshop method that allows business requirements to be collected and visualised in workshops in a lightweight way (Hofer & Schwentner, Henning, 2021).

Domain story according to domain storytelling

Figure 3: Domain story according to domain storytelling

The domain story largely corresponds to the process in the idea sketch.

  1. The client submits an enquiry to an IT system house.
  2. The AI analyses the enquiry.
  3. The AI searches for a suitable solution in the solution library.
  4. The AI proposes a suitable solution to management and development.
  5. Management and Development confirm the solution.
  6. The AI generates an offer with T-shirt sizes and sends it to management and development.
  7. Management and Development generate a quote with prices based on the quote generated by the AI.

Since the team wants to develop a small prototype to show to management, they decide to design APIs for the AI.

API design

Interfaces of AI (marked in blue)

Figure 4: Interfaces of AI (marked in blue)

Artificial intelligence (AI) requires three interfaces:

  1. An interface to be able to import a query in order to subsequently analyse it.
  2. An interface to a solution library in order to find a suitable solution.
  3. An interface to send a created offer to management and development.

The team chooses the interface from the AI to the solution library in order to get results quickly and also to make this minimal solution available to developers in order to simplify current estimates.

They create a visual glossary for analysis. Such a visual glossary uses the terms found and puts them in context (Zörner, 2015). The first interfaces can already be formulated on this basis.

Visual glossary for the solution library

Figure 5: Visual glossary for the solution library

Let us now imagine that we want to query such a solution library. An initial REST interface could look like this:

paths: 
  /solutions: 
    get: 
      description: | 
        Delivered back some solutions out of the solution libraries based on certain keywords and figures 
      tags: 
        - Solution Library 
      parameters: 
        - $ref: '#/components/parameters/Figures' 
        - $ref: '#/components/parameters/Keywords' 
      responses: 
        200: 
          description: Successful operation 
          content: 
            application/json: 
              schema: 
                type: array 
                minItems: 0 
                maxItems: 10 
                items: 
                  $ref: '#/components/schemas/Solution' 
        400: 
          description: Bad request 
        500: 
          description: Internal server error 

An initial mockup can be generated from this interface definition, which forms the basis for further expansion of the prototype. A mockup is a software programme that uses the data from the definition and does not have its own business logic. However, it can already be used to test the suitability of the idea.

The application of the proposed approach

The workshop formats “design thinking” and “domain storytelling” can be easily combined. Domain storytelling can be used in the solution definition phase of design thinking in order to develop a common understanding of the solution strategy within the team.

The resulting domain story can be used to test various scenarios.

Initial mock-ups can be created using simple interface definitions and further scenarios can be tested using a simple client and server. The prototype then forms the basis for further technical evaluation.

The methods of design thinking, domain storytelling and API design thus belong together and form a common basis for the lightweight development of new solutions and testing their suitability.

 

Notes:

If you like the article or would like to discuss it, please share it in your network.

​​Hasso-Plattner-Institut. (2023). Design Thinking. Retrieved February 2024 from HPI Academy
​Hofer, S., & Schwentner, Henning. (2021). Domain Storytelling: A Collaborative, Visual, and Agile Way to Build Domain-Driven Software.
​Zoerner, S. (2015). Softwarearchitekturen dokumentieren und kommunizieren, Entwürfe, Entscheidungen und Lösungen nachvollziehbar und wirkungsvoll festhalten.

Dr Annegret Junker has published more articles in the t2informatik Blog, including:

t2informatik Blog: Micro frontends in practice

Micro frontends in practice

t2informatik Blog: Why I am not superfluous as a software architect

Why I am not superfluous as a software architect

t2informatik Blog: Reasonable limits for self-responsible teams

Reasonable limits for self-responsible teams

Dr. Annegret Junker
Dr. Annegret Junker

Dr Annegret Junker works as Chief Software Architect at codecentric AG. She has been working in the software industry for over 30 years in various roles and different domains such as automotive, insurance and financial services. She is particularly interested in DDD, microservices and everything related to them.