Software, and a software architecture, is a solution to a problem. Without a specific problem, software is a pointless exercise: statements in a formal language with no thesis or purpose. An abstract piece of software akin to the statement: "Time flies like an arrow." It parses (two different ways!) but doesn't solve a problem.

The central issues, then are

  1. Identifying the problem
  2. Developing a solution
  3. Describing the solution

Here, we'll look closely at the description of the solution. The description, like any story, establishes a context or setting (time and place); it peoples this place with actors who have goals and objectives. A good story creates drama by putting the actors in conflict with each other or their setting. The characters typically evolve and change, making moral choices, and eventually resolving their conflict. There are, in a good story, consequences to this resolution. In a movie, these consequences comprise the "third act," and are sometimes overlooked or ignored.

We have, then a general pattern for story telling:

  • Context
  • Problem
  • Forces
  • Solution
  • Consequences

Note that this is a good order, but not the only order. Films will interleave the elements of context and problem during the first act. Some characters (representing the forces to be resolved) may also be introduced during the second act. The solution may be hinted at from the very beginning, or introduced as a twist at the end.

Given this framework or pattern, we can craft a compelling description of a software solution to a problem. Consider what happens when we omit elements of the narrative structure.

Omit the Context. The reader knows the problem, but may not understand why it is a problem. The necessary background is, of course, the context; it does not have to be presented first, but is essential to understanding the problem. Generally, the context is a fixed background against which the problem is solved: it is often a phsyical, legal and social fabric.

Omit the Problem. The reader may say, "nice algorithm but why do I care?" The visionary project plan includes budget, staffing, tools, schedule, but not hint as to why we are doing this.

Omit the Forces. Given the problem and the solution, descriptions of the forces seem redundant. However, without the resolution of various forces, it may not be clear why this solution is the best solution. Most problems have a large number of solutions, including "ignore it." What is essential is the description of why the other solutions are impossible or inappropriate. This shows how the solution optimizes all of the competing forces.

Note that when the forces do not compete, there is no problem. Sometimes, this needs to be carefully and clearly explained. People often propose to build needless or redundant software because they have failed to recognize all of the forces and provide adequate resolution.

Omit the Solution. This is rare, but not impossible. Failing to describe the solution means that it was taken for granted, somehow, and didn't bear to be repeated. Looking back on projects in the past and trying to justify ongoing funding or future development is made more difficult when the obvious is not stated just once for the record. The reader is left with a description of a problem, and perhaps consequences from some unstated solution, but no clear vision of the solution itself.

Omit the Consequences. This is not as severe a problem as omitting other parts of the story. If the forces and solution are presented fully, this may be obvious and not bear repeating. Leaving the consequences implicit may leave the reader unable to understand project plan details, costs or schedule required to create the solution. As with the problem, it is most important to state the consequences "once, for the record."