Now let’s talk about Requirements Documentation. The result of the effort that you put into requirements development is a documented agreement between the customers and the developers about the product that’s going to be built. It’s important that the requirements are fully documented in the way that best captures the process, which is why you want to use software that is specifically designed for requirements documentation.
Software requirements can be represented in a number of different ways. For instance, you can use documents that utilize well-structured, clearly written, natural language; you can use graphical models that illustrate system states, transformational processes, data relationships, logic flows, or object classes; or you can represent the requirements with formal specifications that define features using mathematically precise formal logic languages. Structured natural language, accompanied by graphical models, continues to be the most practical way for the majority of software projects to document their requirements.
As you know, business objectives describe the business problem that’s being resolved – or the business process that’s being improved. You’ll want to summarize the important business benefits that the product will provide in a quantitative and measurable way. State the factors that have the greatest impact on achieving success and specify the measurement criteria to assess whether or not the business objectives have been met.
When the requirement documentation is done, we recommend that you send it out to all of the stakeholders, to let them know what the output of the process will be. Ask them to review it. The truth is, people are always far more committed to making the process successful if they feel they are involved and know the plan.
From a beautiful sports car to the perfect juicy burger, all the finest things in life have certain characteristics that combine to make them great. Excellent requirements have a set of characteristics too. One such characteristic is that they’re Complete. Each requirement needs to fully describe the functionality to be delivered. It’s got to contain all the information necessary for the developer to design and implement that feature.
Another characteristic of excellent requirements is that they are Correct. Each requirement must accurately describe the functionality that needs to be built. The reference should be the source of the requirement or the person who asked for it. It could be a user, for instance. Only users can determine the correctness of user requirements, which is why they should always be involved in the process. Bear in mind that a requirement that conflicts with another requirement is not correct.
Excellent requirements are Feasible. It has to actually be possible to implement each requirement within the known capabilities and limitations of the system. The developers should work with the people that define the requirements to make sure that they’re doable.
Each requirement should be Necessary. Every requirement should be for a feature that the customers really need or are required for compatibility with an external system or regulations.
Excellent requirements are also Prioritized. Assign a priority to each functional requirement to indicate how essential it is to a particular product release. Prioritizing is vital because, if all the requirements are classified as equally important, then it’s hard for the project manager to respond to budget cuts, schedule overruns, new requirements added during development, or other factors that require updates to the development plan.
Requirements should be Unambiguous. Write requirements in simple, concise, and straightforward language so that nobody reading them could possibly misinterpret them. If requirements are not explained precisely and completely, there is the danger that developers will end up trying to fill in the blanks on their own. Requirements that are too ambiguous could also end up creating different expectations on the part of stakeholders, leading to disappointment with the development results.
Requirements should be independent. If a Requirement’s development is dependent on the development of other requirements, it might cause prioritization and planning problems. For example, suppose a customer has selected as high priority a requirement that is dependant on a low priority one. In this case, the low priority feature would have to be developed as well, before developing the high priority feature.
When there is no way to avoid dependencies, you can combine the dependant feature into one larger independent requirement, or find another way of splitting them.
And the last characteristic of excellent requirements? Verifiable. Try devising a few tests or other verification procedures to figure out whether or not the product properly implements each requirement.
There are several requirements attributes that should be recorded during the documentation process. These attributes include: (he numbers them on his fingers)
– Unique ID number
– the date the requirement was created
– its current version number
– the requirement status – such as: Requirements, Design, Development, or Complete
– the origin and source of the requirement
– the requirement type: for example, Mandatory, Optional, or Future version
– the names of the requirement author and the person responsible for ensuring that the requirement is developed successfully.
– the owners of the requirements who will make decisions about proposed changes
– any subsystems to which the requirement is allocated
– a product release number to which the requirement is allocated
– And approval status: That is, Approved, Pending, or Rejected
Other requirements attributes that should be recorded during documentation include:
– The Objective, which is the business objective to which this requirement is related to.
– And also the implementation priority
You have to break down the project into processes, or user stories. Each process represents a sequence of actions that users take to complete a task that will help them to achieve a business objective. For example: In our drapes ecommerce website: one process could be searching for drapes. Another process is selecting drapes and adding them to the shopping cart.
Each process groups a set of features that enable the product user to use the system to complete the task. So you break down each process or story into a list of features. You’ll find that it’s easier to list the features by the order that they’ll be used by the user. For instance, take the process of selecting drapes and adding them to the shopping cart: one feature will be a search engine that enables the user to search for drapes based on criteria like color, size, type of drapes, and fabric. Another feature would be selecting the characteristics of the drapes before adding them to the shopping cart: selecting the color, the size, accessories that can be added to the drapes, and so on.
Once you’ve listed the features of each process, it’s time to start drilling down into each feature. Write a clear description of the way the feature should work and what components it should include, such as buttons, screen layout, field types, value ranges, and so on. The description should be very detailed and very well-organized so that the developers will know exactly what needs to be done. You don’t want to leave anything for them to guess. Usually developers don’t talk to users and clients, so they don’t always fully understand the client needs. If you leave them with too much room for interpretation, then they might take the product in the wrong direction. As a result, the team could end up developing a product that is completely different from what the client expected to get, and then you would need to start the development process all over again or make changes to the product after it has been developed. Obviously that would cost you a great deal of money, waste a lot of time, and leave you with extremely angry clients. So that’s why it is very important to have a clear, detailed, and organized description of how the features should work.
Use simple language, avoid complex sentences, and assume the readers have no basis knowledge of the project. Use consistent terminology, utilizing the same terms throughout the document so that nobody will get confused. If the feature description includes too many items and starts to get too long, you might want to consider dividing it into a few smaller features. The idea is that a feature description should be about a specific functionality. But you want to keep the balance of not going into too much resolution. You don’t define a requirement for every button that you have on the screen. But if a feature includes a few smaller features, each smaller feature has a different role, and requires detailed definition, you should break it into several smaller requirements.
Let’s take for example the shopping cart feature. This is a large part of functionality that should be divided into smaller requirements. For instance: the option to add items to the shopping cart is one requirement. The option to edit or delete items from the shopping cart is another feature. How the shopping cart should be displayed on the screen, with page layout, buttons and fields, is a separate requirement. The payment process is also a feature that we should define independently. So I list the shopping cart requirements under a feature group called Purchasing Process. Each feature in this group will help the user to complete a small part of the purchasing process, until the user can accomplish her business objective of buying the drapes.
Here are three letters you should know: SRS. That stands for Software Requirements Specification. Functional requirements are documented in an SRS, which fully describes the expected behavior of the software system. The SRS also includes non-functional requirements like performance goals and the descriptions of quality attributes. The SRS states the functions and capabilities that a software system must provide and the constraints it must respect. It’s the basis for all subsequent project planning, design, coding, and testing. Customers, the marketing department, sales staff, project managers, the software development team, the testing group, maintenance and support staff, documentation writers, training personnel, legal staff, and subcontractors all rely on the SRS. Needless to say, it’s really important! To document these requirements, you’ll need to use an SRS template, which you can find by clicking on the SRS template below.
Requirements Management software, like Elementool, creates the SRS automatically based on the requirements that you submit to the system. You can even create shorter versions of SRS with a set of a few specific features, in case you want to discuss these features with your team. You do that by simply selecting the features you want to include in the SRS and then the software generates the document for you.
The requirements documentation process isn’t just about writing and recording information. You also have to review the requirements. Any time someone other than the author of a software requirements document examines the product for problems, a peer review takes place. Reviewing requirements documents is a powerful technique for identifying ambiguous or unverifiable requirements. You can also detect bugs in the design during the review process before they are developed. It costs 5 times more to fix a bug at the development stage than in the requirements stage.
There are both formal and informal types of reviews. The informal types include a peer ‘deskcheck’, where you ask a colleague to look over your work product; a ‘passaround’, where you invite several co-workers to look at the document at the same time; and a ‘walkthrough’, where you describe the document and ask for comments on it.
A formal peer review, on the other hand, follows a well-defined process. A formal review produces a report that identifies the material, the reviewers, and the review team’s judgment as to whether the product is acceptable. The review produces a summary of the defects found and the members of a formal review share responsibility for the quality of the review.
Digging deeper into the review process gets us to the inspection process. Any software work product can be inspected, including requirements and design documents, source code, test documentation, and project plans. Inspection is a well-defined multistage process that involves a small team of trained participants who carefully examine a work product for defects and improvements. Participants in the inspection should represent four perspectives: the author of the work product, the author of any predecessor work product or specification for the item being inspected, the people who are responsible for work products that interface with the item being inspected, and the people who will do work based on the item being inspected (such as a developer, tester, or project manager). We recommend limiting the team to no more than six participants.
There are four major roles in the inspection process. The Author creates or maintains the work product being inspected. The Moderator serves as the inspection leader, planning the inspection with the author, coordinating activities, and running the inspection meetings. The Reader paraphrases the SRS one requirement at a time, with the other participants then pointing out potential defects and issues. By stating the requirements in her own words, the reader provides an interpretation that might differ from that held by other inspectors. The final role is the Recorder, who uses an Issue Tracking software to document the issues raised and the defects found during inspection meetings.
The inspection happens in stages, starting with the Planning phase, when the author and moderator plan the inspection together, deciding who should participate, what materials the inspectors need to receive before the inspection meeting, and how many meetings they’ll need to cover the material.
The next stage is the Overview Meeting, in which the author describes the background of the material that will be inspected.
The Preparation stage happens prior to the inspection meeting, and it involves each inspector examining the product to identify possible defects and issues that should be raised. Up to 75% of defects are found during this phase, so keep a sharp eye.
Then it’s time for the Inspection Meeting. During this meeting, the reader leads the other inspectors through the SRS, describing one requirement at a time in his own words. The inspectors bring up possible defects and other issues, while the recorder captures them on a form that becomes the action item list for the author. The purpose of the meeting is to identify as many major defects in the document as possible. The meeting shouldn’t last more than two hours, but if you need more time, schedule another meeting. At the end of the meeting, the team will decide whether or not to accept the requirements document as is, accept the minor revisions, or indicate that major revisions are needed.
The Rework stage is where the author spends time reworking the requirements after the inspection meeting. And Follow-up is the final step, in which the moderator works with the author to ensure that all open issues have been resolved and errors have been corrected. The entire process ends when all of the issues raised during the inspection have been addressed, or any changes in the document have been correctly made, or when the document has been checked into the project’s configuration management system.
To help inspectors look for typical kinds of errors in the products that they inspect, develop a defect checklist for each type of requirements document. This draws the inspectors’ attention to historically frequent problems.
There are a lot of challenges associated with requirements review, and fortunately our program will help make the process much easier. There are a few tips we’d like to pass along to you, though, to help you with other aspects of the process. For instance, we know that large requirements documents, like a several hundred page SRS document, can be seriously daunting. So to avoid overwhelming the inspection team, try performing incremental reviews throughout requirements development. Identify high risk areas that need a careful look, and use informal reviews for less risky material. Definitely consider using several small teams to inspect different portions of the material. Also establish several small teams to inspect the SRS in parallel and combine their defect lists.
And, even if you have a long list of potential participants for requirements inspections, try not to let your inspection team get too large because that complicates things like scheduling meetings and reaching agreement on issues. Make certain that every participant is there to find defects, not to be educated or to protect a political position. Also, we’d recommend that you decline the participation of people who duplicate a perspective that’s already covered.
Finally, we should talk a bit about the project change control process. As requirements evolve and grow during development, projects often exceed their planned schedules and budgets. Frankly, these plans aren’t always based on a realistic understanding of the size and complexity of the requirements. And frequent requirements modifications just make the problem worse. To manage scope creep, you should begin with a clear statement of the project’s business objectives, strategic vision, scope, limitations, success criteria, and expected product usage. Evaluate all proposed changes and requested features against this reference framework.
Creeping requirements include new functionality and changes that are presented after the project requirements have been baselined. The problem is not that requirements change, but that late changes have a big impact on work already performed. If every proposed change is approved, it might appear to project stakeholders that the project will never be completed. It’s kind of like when my husband and I recently re-did our kitchen. There were many times during the process that I thought ‘Oh, maybe it would be nice to also add this on,’ or to change the type of tile along the counter. But for those changes to work, we would have had to start again from scratch. And not only would that have been a pain in the neck, it also wasn’t in our budget.
Of course some requirements evolution is legitimate or unavoidable. We know all too well that business processes, market opportunities, competing products, and technologies can change during the time it takes to develop a product. But uncontrolled scope creep, in which the project continuously incorporates new functionality without adjusting resources, schedule, or quality goals, has a harmful effect. A small modification here, an unexpected enhancement there, and soon the project has no hope of meeting the planned schedule. So you should evaluate every proposed requirement or feature against the business objectives, product vision, and product scope.
The most effective technique for controlling scope creep is being able to simply say no. Philosophies such as ‘The customer is always right’ are fine in the abstract, but you pay a price for them. If you find it difficult to say ‘No,’ try saying ‘Not now’. At some point you have to freeze the requirements for a specific release or you will never complete it.
It’s very rare to define the entire project upfront. There might be outside forces that affect the project during its lifetime. For that reason, change is part of the project. It’s important to have a process in place that’s agreed upon by the client. Change Control is the management of anything that wasn’t in the original scope, requirements, schedule, or cost estimates of the project. It involves updating and maintaining the project documents and the resulting changes to quality, risk, cost, schedule, and so on. Change control includes adding new requirements based on new functionality that is needed, deleting requirements of features that have been canceled, fixing errors in the baseline document, and scheduled changes.
Submitting a change is done by using the ‘Change request’ form. It can be done by using a software form, such as Issue Tracking, that is part of the control management system. A change request should follow a mini-requirements creating process and go through the stages that we described earlier.
The change request should contain the complete snapshot of the change. It needs to include the description of the change, the reason for the change, and an explanation of the benefits to be received from the change. Your Requirements Management software should be able to track all that information. It should also be classified as a new change or a correction to existing requirements. Send the change request over to the development team for analysis, time and cost estimation, and design. Pass it around to all other stakeholders who might be impacted by this particular change. It should then be approved and added to the development plan. When the process is done, be sure to update the requirements records in your Requirements Management software with the changes and notify all teams about the change.
This clip ends the Requirements Management section of the program. Next we are going to learn how to estimate and manage task schedule. Stay tuned.