Telling Stories

The author looks at the parable of the Ark, focusing on the level of detail that is provided to Noah about the material, dimensions, and intended purpose. If he had merely said "build a boat," the outcome may have been unsuitable.

He also spins a parable of his own about sending someone to a store with a shopping list - the less detail you provide, the less likely it will be that you will get back what you expect, want, and need.

The more complicated the item, the more detailed the requirements must be to provide the person who is expected to deliver it with a clear knowledge of what is needed.

In the business world, the task is complicated because it is often not one audience to serve: multiple people will be affected by the outcome, and will want to have input into the design, so you must ensure that the requirements suit each of those needs.

Why Do We Learn Better From Stories?

Using a narrative enables the listener to identify with the role of the protagonist. In software development, using narrative to describe the role of each user (whether they interact directly with the system, provide inputs, or receive outputs) provides a clear and compelling sense of their needs, in a way that sketches, diagrams, and descriptions cannot.

How Do Story Elements Relate to Requirements?

The author suggests considering the elements of fiction - he does this in a very sloppy way and misuses terms. Not worth preserving notes.

What Are Software Requirements

In a fundamental sense, a requirements document describes a business problem and indicates an IT solution, using language that can be commonly understood (by business and IT). Ideally, it will do this in precise, measurable, and testable terms.

Of importance, the requirements do NOT explain how the system is built, prescribe specific technologies, or get into the project planning (schedule, costs, and resources) - and it is counterproductive to serve these concerns.

Who Are They For?

The primary audience of requirements are the IT developers who will build the system, but other audiences should not be ignored: the management who control budget and resources; the project management staff who will oversee the development; the champions who will "sell" the solution to the users; etc. Fundamentally, anyone who will be impacted by the system, whose effort is required to build it, whose cooperation will be required to use it, or who have the power to stop it from going forward, should all be considered.

Are Software Requirements Different from Business Requirements?

These terms are used inconsistently in IT - to be clear, the author means "software requirements: to broadly mean any requirements that will guide the development of an IT solution. It includes software requirements, business requirements, technical requirements, functional requirements, nonfunctional requirements, or any other "requirement."

These subcategories are often useful in determining who needs to be in the room, and ensuring all perspectives are covered - but from a functional perspective, the distinction is unimportant. A requirement is a requirement, regardless of its nature or origin.

Why Projects Collapse Without Detailed Requirements

The author tells a story of his own about a typical problem with software development. It's full of hypothetical situations and hyperbole, but the problems are real. While the business rules cannot solve some of these problems (conflicting desires, ulterior motives, the politics of who is even included in the discussion), it can confound them by creating a written agreement that is unclear to all involved - and when the blueprint is bad, the product is bad.

Why Have We Turned from the Path of Righteousness?

The majority of people know that a clear blueprint is important, but suggests that there are a number of reasons that we have evolved them in the wrong direction.

To begin with, computers have always been a specialized area, intimidating to laymen, who have been content to step back from IT and let the wizards handle things. The wizards, meanwhile, have entrenched themselves by supporting and perpetuating the smokescreen.

Those who have knowledge in IT generally have very poor communication and interpersonal skills, so even those inclined to lift the veil have often been incapable of doing so.

A failed software project, especially one with a high cost, can be disastrous to an organization, and to the careers of those involved. Much of "documentation" is done not to describe a successful solution, but to facilitate placing the blame on others for its failure.

Failure to communicate clearly has led to the development of structured methods of communications (diagrams and other structured documents) that have grown in complexity, to the point where they end up making communication even less clear.

The rushed pace of business does not provide sufficient time to develop good plans, and focuses instead on the more evident and measurable act of building rather than the less measurable but more important act of planning.

Planning is not perceived as being "real work," and because it has been done poorly, there is the perception that it is inherently flawed

There is the perception that size is evidence of importance, so many planning efforts result in the production of "phone-book-length documents and wall-sized diagrams" that do a poor job of describing requirements rather than a project plan that is brief and clearly written.

Can Stories Get Us Back on Track?

The author believes so. At it's core, any project is geared to enable someone to do something, and the success or failure of the solution is in its ability to meet that core need. "Someone doing something" lends itself well to narrative, and if the story can be kept simple and straightforward, it will provide a clarity of common vision and, ultimately, to a better outcome for all.

Defining the story should be the first step in planning, with details about other requirements (what systems are in play, what legal obstacles are present, the database structure, etc.) being added later. What's more, these details will make far more sense in the context of the story rather than as abstract descriptions without a point of reference.

Making Structured Analysis into a Story

"Structured Analysis" (SA) is a technique used to develop requirements that departs from narrative. It's noted that its proponents often denigrate "narrative prose" approaches in favor of this technique, as they viewed narrative as being unfocused and lacking sufficient detail. The author asserts that these individuals dismiss narrative, itself, as being bad - but only because the critics, themselves, do it badly.

SA involves itself with assembling a large amount of information about the company's information systems and then describing how they can be utilized, altered, or augmented to yield the desired output or result. The determination of the tasks involved (who must do what to make this happen) is dealt with as an afterthought, if it is considered at all.

While SA provides a high level of detail, much of this detail is completely irrelevant to the task that needs to be accomplished. By design, it is a systems-based approach to performing a task, which often puts the capabilities and characteristics of the system before the task itself. The result is a cloud of data that is no less incoherent and unstructured than the kind of poorly-written narrative the creators of SA were looking to avoid.

As evidence, the author relates an anecdote of a project that created a project requirements document that was over 400 pages in length, that did not once mention what the system was intended to do (i.e., "this system will enable customers to buy and sell equities"). He concedes that this is an extreme example, but it is not entirely uncommon to have to do a great deal of reading and examination to figure out the purpose of a project.

This is the reason the author sought a return to narrative - rather than abandoning it in favor of another system (which turned out to be even worse), he seeks to evolve narrative and, more importantly, to help others to do it well.

Who Should Do This Work?

Currently, software requirements are often written by software developers and project managers, and they are rotten at it. They understand the systems, but do not have adequate communication skills, consider the task to be unimportant, and have their own agenda (often, to do as little work as possible).

In instances where business people are involved in writing requirements, the problems are very much the same: they understand the business, but do not have good communication skills, consider the task to be unimportant, and have their own agenda.

The author's suggestion: find and hire people with good writing skills, and who are not skewed to one side or the other in terms of their familiarity and agenda. Specifically, hire writers - and not "technical writers" (who are often engineers with a modicum of skill), but people whose forte is communications.

He rails for a bit about how communication skills are undervalued by IT, and that this is the reason so many things (requirements, procedures documentation, and user manuals) are done very poorly.

His recommendation to those who are reading this book because they have been tasked with writing requirements (whose "real" job, and real skills, are business or IT), should step up and admit that they don't have the skills to do the job, and campaign for getting someone who does involved.

Failing that, be aware that the skills you need are communication skills, that you will need to develop them, and you will need to make clear communication your priority in developing requirements or any other form of documentation.