Home | Login | Recent Changes | Search | All Pages | Help

RequirementsReverie

Pitch sorting - a requirements reverie

Background

Objective: train my hearing

I'm currently learning music, and I'm going about it in that systematically unsystematic way that I have - figuring out the boundaries of the domain rather than attempting to follow a charted course through it.

A friend of mine describes a "game" used in musical training; the goal is to train one's ear to recognize the relative pitch of sounds - whether "this" sound is higher or lower than "that" sound - to a very fine grain. The student should eventually be able to distinguish pitches that are one comma apart - the ninth part of a semitone, which itself is the musical interval between, say, A and A# on a piano.

I haven't found software that does that, and the hardware seems hard to find - my friend describes a "training xylophone" with nine blocks of wood of equal lengths but differing pitches, that must be sorted in ascending order. So I decided to write such a program, and turned it into a requirements-definition exercise, intending this document to be "the requirements".

Requirements - a digression

Aye, there's the rub. What are "requirements" for a program like that ? What they are not is a description of how the program behaves once I have finished writing it - even though that's what, it seems, most requirements docs want to be; a user's manual for software as yet unwritten.

Rather, the requirements are about me, the intended user. They are about distinguishing between two categories of program behaviours - those that advance me even one small step towards my objective, and those that don't. Ideally the program should be all about the first category, and contain elements of the second category only insofar as they are absolutely necessary to support behaviours in the first category.

Rather than the requirements - literally "what is, objectively, required to advance my purposes" - I, as the program designer, can only hope to have a theory of the requirements. That is, I don't know with 100% certainty that any program design will make its user better equipped to hear fine distinctions between sounds; I don't know with 100% certainty that the program design I have in mind will do that.

What I do have is good reasons to believe that some designs will achieve that objective, based on some broad models of how learning occurs, of what music is about, and so on. Specifically, I hold that repeated performance of a task will improve the performer's ability to perform the task, as long as she is presented with a task difficulty that is neither well beyond her current ability, nor well within it. I also hold that discriminating two sounds of varying pitches as "higher" or "lower" than one another is already, broadly, within most users' ability, and in particular within the ability of my intended user. I hold that by varying the differences in pitch that the user is called on to discriminate, the user will eventually improve her pitch discrimination to a specified objective, or asymptotically approach the limit of pitch discrimination that she's intrinsically able to achieve. I might be wrong about any of that.

In addition to a theory of the learning process yielding a theory of the requirements, I am in possession of a model for structuring the task around which the learning process is organized: sorting nine "things" by ascending or descending pitch.

I could just as easily work with alternative models; for instance, presenting two sounds in order (a melodic interval) and asking if the first sound was higher or lower than the second. Or I could require the user to familiarize themselves with a number of pitches, then sound another pitch at random and ask the user to pick the closest pitch lower than the reference pitch. To the extent that "pitch sorting" is a requirement, then a requirement is a bet: I am betting that the sorting task is a good way to go about achieving the stated outcomes. The bet might not pay off - something about the organization of the task, or the interaction of the task with the computer environment, could turn it into an ineffective learning experience.

Models of operation represent further requirements choices. The program need not be graphical; command-line operation could be suitable. The abstract model of the program is that of a collection of "tagged" objects, where the tags are obscure and provide no clue as to the relation between pitches associated with the objects. We can imagine a non-graphical mode of operation in which typing a digit N (in the range 1-9) produces the pitch randomly associated with the label N; the goal is to type in a sequence of digits that results in playing the pitches in ascending or descending order.

If the program is to be graphical, a "direct manipulation" idiom seems appealing, as it will tend to make the representation of the task transparent and leave the user with the impression that she's "just moving stuff around". That requirement would also be a bet. Typically, requirements like this can be chronologicall ordered by a "prototype" strategy - let's do the non-graphical version first, to shake out further requirements, and because it won't take as long to do.

Some requirements arise from "misfits" - arrangements that would be fatal or problematic to achieving the task outcomes.

For instance, if the program is unable to cause the user's PC (or device) to emit sounds at the proper pitches, then performance of the task will have little to do with ear training. Being able to produce sounds at a specified pitch is a requirement in that sense.

Inaccurate feedback to the user would be fatal as well; say, if the program reports as incorrect an ordering of pitches which is correct, or as correct an ordering which is incorrect. At best these will leave the user wondering what the heck is wrong with the program; at worst they will "un-train" the user's hearing.

Both of these "misfits", I realize, stem directly from the model of the learning process that is predicated above - the theory, which is something rather broad and vague, does yield definite requirements, by way of misfits.

Non-domain "misfits" exist as well - for instance, it would be inconvenient if the program only ran on some device that the intended user doesn't own.

By now I think I have a good enough understanding of the problem domain, in the abstract. I have a list of candidate high-level requirements. I can turn my thoughts to considerations of implementation. These generate "requirements" of their own, which turn not on facts about the user but on facts about the provider of the programming capability. As customer, I have the right to choose any provider I want - but having made that choice, I have a responsability to the facts concerning that provider. For instance, it is a "requirement" that the program should run on Windows platforms, because that's my development platform. It is a "requirement" that the implementation language should be Ruby, because that's what I'm most motivated to use, and I'd turn down a non-Ruby project.

At some point I need to turn my "requirements" into a plan for implementation. (Why ? Because a plan is a feedback instrument; when I have a plan, I know that each time I deviate from it is an occasion for learning something.) I think it's at that point that most people would write the main part of a "requirements document": an ordered breakdown of sub-objectives that, once completed, will add up to the desired outcomes. It would be handy to represent that as a outline, for instance as follows:

The requirements - finally!

1 Allow the user to perform a pitch-sorting task
1.1 Model the pitch-sorting task in a non-graphical environment
1.1.1 Hold a set of 9 objects representing ascending pitches at equal intervals
1.1.2 Randomize the set
1.1.3 When the user keys in a digit 1-9, sound the corresponding note
1.1.4 Recall the last 9 keys pressed by the user
1.1.5 When the sequence in 1.1.4 forms the series of ascending pitches, thell the user she won

The outline representation is convenient but false: the "requirements" are structured into more dimensions than we can represent in a tree; different requirements may exist, say, on different "planes". For instance, modeling the task graphically or not is a dimension of choice different from adding the requirement "allow the user to specify the interval between pitches, in commas, from 1 to 9", which is itself different from the requirement "give the user feedback that she won by playing the nine pitches in an ascending scale", versus "by printing out 'you win'". Also, the requirements form a network rather than a tree - you see this when you consider the question "if I change this, what else may have to change" for each requirement in turn.

What we gain from "documenting" the requirements in such a outline structure is the ability to plan the implementation as a series of discrete efforts, each of which has a mesurable, testable outcome. That's valuable.

Notice, though, that in the above "The requirements" don't tell the whole story. I can't hand that to the developers and expect that they will do a good job, even if I add a glossary of terms used (such as "pitch"), even if I attempt to specify the technical design unambiguously ("to sound a note at a given pitch, emit a MIDI pitch-bend message, followed by a note-on message, followed by a wait of half a second, followed by a note-off message"). There's too much structure to the requirements that doesn't show in a tree representation.

In the above, though, I think I got to an adequate result: I obtained a crisp and clean separation between various levels of concern; those I have as the intended user of the program, those I have as the "sponsor" of the development effort, those I have as the developer. The entire conversation, though internal, was worthwhile and helped me establish a plan, which will then help me monitor and steer the effort.

Conclusions

For any given software effort, "the requirements" are a complex and dynamic object, an evolving mix of theory, bets, constraints, preferences, and interrelations between all these things. No single technique is adequate for communicating or documenting all of these, and no single document can possibly capture "the entirety of the requirements". Consequently, a strategy for producing software which focuses on "getting the requirements document right" is bound to produce disappointment instead.

Rather than focus on the documents, focus on the people who will be executing the strategy. At each stage of the project, figure out what they need (and prefer) to know about the requirements in order to best perform their tasks. Be sure to have a broad "toolkit" of techniques to represent various aspects of the requirements. For instance, represent the core theory as one page of narrative, the implementation plan as an outline, "what the program will look like" as drawings on a whiteboard. Always keep in mind that "the requirements" are not a static document, but an ongoing conversation which spans the entire project.

LaurentBossavit 2005.02.20-23