A requirements documentation mistake

Learn from an early mistake of mine

At a previous employer, the first time I played the role of requirements manager (technically, program manager – with responsibility for the functional spec), I made a bunch of mistakes – this post is about one of them.

The setup

We were engaged in a high-pressure, tight-deadline, under-staffed project with a lot of visibility (Fortune 100 CEO visibility). This custom software development project was expected to yield savings for our client in the $100 million (USD) per year range.

We had a novel situation in that we staffed the development team a week before I was pulled off another project to join this one. There were 20 brand new, fresh out of college developers, on the opposite side of the planet, chomping at the bit to actually have some work to do. We did not staff any senior developers / architects on the project for almost six months. We did have experienced technical consultants on site at the client, managing all of the systems integration and deployment and logistics issues. They were not available to make product development decisions.

The project was one that was designed to improve both management accounting and sales decision support processes for this large company. Understanding the objectives required relatively deep business domain expertise. Our development team did not have that expertise, and our business consultants were already overloaded with rainmaking and pathfinding activities.

We were building and deploying this software with an incremental (not waterfall) deployment strategy – with anticipated quarterly rollouts. Once we got our arms around the amount of effort required to implement the first delivery, we had to adjust our schedule – the first deployment of anything was going to take six months.

The mistake

There were many mistakes made by many people. The one we’re talking about today has to do with documenting requirements at the right level of abstraction.

I can’t share the particulars of the underlying requirements, so I will describe the user interface. We had a user interface that allowed people to view a large set of data – the results of a complex OLAP query, presented in a concise form to the users. A user would commonly want to view this rolled-up data for multiple items, and would specify parameters by which they would want to filter the results for display. It was important to these users that they be able to sort the results (presented in a table) by any of the columns in the table.

Our development team (with a development manager, but no senior developers) was given a set of functional requirements from me, and a screen mockup from one of the HCI designers on the project. The requirement stated that “users must be able to sort the results by any column.”

With what we all know today – I already messed up, because I specified implementation details in the design (“column” should have popped up on the radar, and arguably “sort”). What I should have done was specify that users are able to view the results in any order based upon the displayed parameters.
The next paragraph will have you rolling your eyes, smacking your forehead, or shaking your head.

Our developers were not satisfied with “sort” as a requirement – it was too ambiguous. I complied with their requests, clarified alphanumeric sorting, and thought I was done. In the next cycle of clarification (remember, our development team was working twelve hours time-shifted from our on-site team), I had to agree with them that there was no room in the UI to present a sort-by control, and suggest that they sorted by clicking on the columns. The next day, I was asked to specify if the sorting was ascending, descending, or both. The day after that I was asked to decide if the user would be able to restore the results to their original sequence. The following day, I clarified the desired default sorting order, and what to do in the event of ties (use the most recently sorted column to determine ties, or sort in order from left to right on the page, or something else).

My mistake – I answered all of the questions, documented the default sorting paradigm, linked all sorting requirements to that component, validated (and often gathered) all of the answers from other technical members on the team, confirmed with end users. We had a very consistent and unambiguous definition of how to interpret a requirement that users be able to sort a table by any column.

Hindsight is 20/20

Remember – this is a $100 million (ROI) project. And we’ve got hours invested in defining and documenting how sorting should work. I definitely did not have my eye on the ball.

What I should have done was defer to the “design lead” on the development team (who did not exist at that time), while escalating the issue with our management team until someone was appropriately staffed in that role.

I never should have put that level of detail or effort into the documentation of sorting functionality. It bloated our functional requirements document and blurred the line between requirements and design (crossed it, really). There were many examples of this type of detail, specifying a lot of user interface behavior and algorithmic interpretation of requirements.

We also had an extensive data dictionary explaining the specifics of all of the management accounting requirements – gross profit margin, trailing twelve months revenue, oligopoly metrics and a hundred other terms defined in detail. This, it turns out, was a very good thing – people were still using that data dictionary years after our initial project was completed.

This highlights both the critical need for someone to design an application, and for people to understand the domain in which they are being asked to work. Both the intimate domains and the telescopes… posts were inspired by memories of this experience.

How else could I have avoided this mistake? Tell us in the comments.