Requirements specification. Basic principles
Writing requirements specification is one of the first stages of the project development. It precedes the system development. The requirements specification describes the business domain, the existing infrastructure of the customer, the requirements for the created functional as well as non-functional requirements. The resulting document is useful for both the business user so that he made sure that all of his wishes for the future system had been taken into account, and for us to assess the cost of system development.
It should be noted that we try to avoid the term «Requirements specification» in our everyday analytical work. It is way too overloaded with senses and it is often unclear what it actually means. We use the following terms instead: «Business requirements» (BRD – Business requirements document), «Functional requirements» (FRD – Functional requirements document) and Technical and Architecture requirements (TAD – Technical Architecture document). Here, however, we shall use the term Requirements specification or simply Requirements in order to simplify the description. The document, which we mostly use for communicating with our customers, consists of70% ofbusiness requirements, 20% – functional requirements and only 10% – technical and architecture requirements. Of course, this proportion varies depending on the specificity and technical complexity of the system.
The main success factor in the development of the requirements is well-developed communication with the customer. After all, the task of analysts is to actually perform the brain-dump and present the results on paper in a structured way. It is very important (1) to speak your customer’s language so that you didn’t have to spoon-feed the domain concepts that are obvious to an expert, and (2) know how to listen.
Below, we present the principles that we follow when writing requirements specification, and illustrate them with excerpts from the requirements specification we developed for a major Internet company’s multi-component system of banner advertising.
The structure of requirements specification
Each requirements specification contains a number of core units. They define the purpose of the document, the terminology and the general context of the project. Typically, the first part of the document is as follows:
1. Table of contents
2. Change History
3. Participants of the project
4. Document purpose
5. Terminology
6. General Context
Whereas the beginning of the document provides general, conceptual information about the system being developed, the second, main part of the document presents the detailed business and functional requirements for the system essential for development cost estimates.
In the section “Terminology” of the requirements specification for banner system we define such concepts as Pageview, Click, CTR, Coverage, Contact Frequency, File-Schedule etc.; the “General Context” describes the key business processes of the customer related to the placement of banner advertising as well as the system environment, the current role of company managers and access rights. It is worth noting that in this particular case, the system was not built from scratch. Previously, the company managers were using other banner advertising system, different from ours. Otherwise we would have to dedicate a separate chapter to the roles and access rights analysis.
7. Banner placement system
8. Interaction with the billing system
9. Banner Engine
10. Banner Engine technical description
The largest section of our requirements specification is «Banner placement system»; it is dedicated to the core of the developed system and contains all the requirements directly related to the advertising spaces management system. Given the nature of this project, we have devoted a separate section to the interaction between the banner and the billing system. The requirements for more or less independent statistics component were also placed to a separate section. This is perhaps the main system component for the advertising companies’ clients and managers of the advertising agencies.
A separate section of the requirements specification describes the requirements for the Banner Engine component, responsible for the display of banners, statistics accounting, its processing and saving in a form suitable for further analysis and reporting.
Technically, it is the most complex and most highly loaded component of the banner system. That’s why we have included a section containing some of the technical and architectural details associated with the work of Banner Engine. Besides all, it helps to minimize risks when evaluating the cost of the system development, because depending on the chosen architecture the complexity may be drastically different.
Each requirements specification differs in size, number of illustrations and number of versions. For example, the document for Banner sysem consists of 44 pages and contains 15 illustrations. It took about a month to prepare this document and there were about 8 iterations with the customer.
Business vs Functional requirements
The requirements specification contains both the business requirements and functional requirements:
– Business requirements describe exactly WHAT the system should do, speaking the business user’s language. Business requirements, in particular, should be clear to the manager with no technical training and experience.
– Functional requirements describe HOW certain actions are performed in the system. At the stage when we write requirements specification, the functional requirements are usually provided only for the most complex project blocks. Deepening in the complex areas allows reducing risks in the subsequent assessment of the project. Typically, the functional requirements include block diagram, state diagrams, flow charts, and are complemented by layouts of the most complex screens.
An example of a business requirement:
«For an advertising campaign, it is important to accurately track the limit of pageviews, in order to avoid financial losses associated with the banner pageview above the paid-up limit. In addition, there is a problem of restricting banner pageviews to one user, for example – no more than N times a day».
An example of a functional requirement:
«To solve this problem [see above] we should use an external service to which the banner servers will access at each pageview. Since this service is the point of failure, banner servers must correctly handle the situation in case the external service is down or responds with delays».
Usually we include the following:
Requirements specification contains information about roles and key user scenarios in the system being developed.
E.g. in the document for banner advertising system, we present a scenario of creation of the advertising space by a user in the role of Administrator.
Name of the scenario: Creating advertising space
Role: Administrator
An example of a functional requirement:
«After adding a new media site to the system, the administrator must create the associated advertising space. When creating advertising space he must specify the site , the type of location, supported banner formats, size, frequency of exposures (for static locations). After the advertising space is created it becomes available to the managers who place the advertisements.
Each advertising space receives a universal identifier used by the content management system in a query to display banners. To do this you need to make appropriate changes to the code of the page».
Requirements specification contains requirements for the integration of the developed system with other external and internal systems used by the customer.
In the context of requirements specification for the banner system it is integration with the company’s content management systems, billing, authentication and storage of user data.
«The banner advertising system is connected with three external modules that operate in the company environment: company’s content management system, billing and authentication system and user data storage». Each display is accompanied by a request from the content management system to the Banner system. These systems also share common sites and advertisements identifiers, as well as concerned names of the parameters of targeting».
In the requirements specification we usually include glossary, explaining the meaning of technical terms used in the document. It is important to accurately determine the meaning of the terms which will be used in the document.
«Placement (the unit of placement, the line of a media plan) is the notion which combines the banner you want to display, the advertising space, which will display the banner, as well as the rules of banner display. The rules of banner display define the placement period, parameters of targeting, placement limits, size, etc. Virtually all advertising campaigns consist of placements».
Contact frequency is the number of unique visitors who have looked at a banner ad a certain number of times. For example, contact frequency 5 – means the number of unique users each of whom saw this advertising banner at least 5 times. The contact frequency 1 = = coverage.
Basic principles
In writingrequirements , we do our best to use the graphic materials for visual and concise presentation of information. A diagram can often replace several pages of text. In this context, we aim to draw requirements, i.e., to representat all more or less complex pieces of the system in a graphical form using text merely as comments to the graphic materials.
Typically, the business managers do not have time to study the multipage technical requirements. Viewing the images gives them a visual representation of the basic features of the system being developed. As a consequence, it improves the communication between the business users and us, with the quality of the requirements increasing as well.
The following diagram illustrating the structure of advertising campaigns and the relationship between basic concepts within the advertising campaigns, has saved us a few pages of text.
If necessary, we use interface mockups or functional wireframes, which, while not definitive, demonstrate the basic user interface functionality.
Here is a prototype of the advertising campaign editing screen which was included in the requirements specification for the banner advertising system.
Due to the prototypes at the development stage, the customer knows how the system interface will look like.
Requirements should be written in plain language so as to be intelligible to the business users, including senior manager who does not have technical skills; they must contain minimum technical terminology. The faster the user “gets” the content of the requirements specification, the more effective our communion will be.
Experience in the business domain
When creating a requirements specification, the experience of developing similar systems is of great importance. It helps to quickly delve into the business processes and customer needs, do many things which previously seemed to be complex “by analogy”. The experience gained in the field of business management systems, large Internet projects, financial systems, e-commerce systems allows us to apply this knowledge to each subsequent project we work on. Prior to receiving an order for banner advertising system mentioned above, we developed several banner systems. We know well how the banners work; we have extensive knowledge of the terminology of this domain. Based on our experience with other banner systems, we have suggested our customer many simplifications and original solutions not just in the technology field but also in their business.