Writing good requirements is more than just taking dictation. It is about documenting the goals and needs of the stakeholders (users, project sponsors, etc), in language that the creators of the system (developers, testers, etc) can read. The requirements have to be complete and correct, and they also have to be unambiguous. Determining the right level of abstraction for our requirements is an art, and can be the difference between usable requirements, and a lot of wasted time (or worse, a failed project).
In a recent presentation a St. Edwards University, I described functional requirements documentation as seeing the solution at one of three levels – a telescopic, macroscopic, or microscopic view. Each view represents a different level of abstraction from too abstract to too detailed. When functional requirements are documented at the wrong level, they aren’t actionable.
Telescopic view
When functional requirements are described too abstractly, they don’t provide enough information for implementation teams to properly scope the project. They also introduce too much risk – risk that the delivered product will not meet the needs of the stakeholders. Some examples:
- Users can access the parts of the system that they are authorized to access.
- The system will support 100 salespeople who submit quotes.
Microscopic view
When functional requirements are documented to an excruciating level of detail, they become just as unusable. There is the risk that too much detail, esoteric data, jargon, or logic can hinder validation with the stakeholders. We also run the risk of limiting the creative process and constraining the development team to an overly narrow definition of a solution. By writing these low-level, micro-managing documents, we are pulling the design process into the requirements process, where it doesn’t belong. In this post, we talk about how Shakespeare was responsible for both the spec and the design of his plays. As several commenters point out – that’s not the role we ask people to play in IT organizations.
In any system, the size of the requirements document grows proportionally with the level of detail – increasing the costs of maintaining the system. In large systems, this quickly turns a project into a quagmire of clarification and confusion. An example:
- The system will synchronize transaction records between databases on the regional servers by transmitting change information via XML, updating every hour at the top of the hour. Concurrency conflicts will be resolved with “latest wins†semantics, adjusting for the time-zones in which the servers run, using the transaction times (associated with the underlying data) as recorded on the regional servers.
Macroscopic view
As Goldilocks would say, this one is just right. The minimum level of detail required to be unambiguous in expressing a required capability of the system. No implementation ideas or constraints. Not too abstract. Not so complex that a “shorter version†is required to communicate with the stakeholders, and not so over-simplified that the developers can not implement it without getting extra information. Some examples:
- The system will allow the user to specify her state and county of residence (in the USA). When the user indicates her state of residence, the selection of possible values of county are filtered to only the counties in the selected state.
- Users will have read-only access to their payroll information, but they will not be able to view other user’s payroll information. Some users will be identified as managers, and all users will have their manager identified in the system. Managers will have read-only access to the payroll data for all users who have them listed as their manager.
- The system will support 100 salespeople. Each salesperson will submit an average of 100 quotes into the system per week. The system must validate (or invalidate) each quote within ten seconds of quote submittal when the salesperson accesses the system via the local LAN.
- The system will maintain synchronized transaction databases on each of the regional servers. The servers will be synchronized on at least an hourly basis. Concurrency conflicts will be resolved with a “latest wins†semantic, based on transaction time as recorded on the regional server.
When teaching others how to write functional requirements at the right level, we propose the following to find the balance between vagueness and verbosity:
- Be precise enough for a developer to design and implement a solution that satisfies the customers (stakeholders + users)
- Maintain use of language that is clear to the customer
- Be unambiguous enough to allow for definition of validation tests
- The requirement is written in language that is solution-indifferent. No implementation decisions
Do you have any examples of requirements that you had to deal with that were either telescopic or microscopic in their detail?
4 thoughts on “Telescopes, Microscopes, and Macro-scopes – How to View Requirements”