Example of writing a Software Requirement Specification

Your project should have a good start point. A group should lead the customer into the demand inspiration stage and you should write the Software Requirement Specification. This description is a little big, but the customer will pay great attention to it. Therefore, the description must be accepted. Now you are designing one of the features and have found some problems with requirements. You can explain requirement 15 in different ways. Requirement 9 is the opposite of requirement 21. Which one should you trust? Requirement 24 is very vague and you don't understand it at all; you have to spend an hour discussing requirement 30 with two developers, just because you have a different understanding of it; and, the only client that can clarify these questions has not answered you. You are forced to crack the meaning of many demands, and you can expect that if you are wrong, you have to do a lot of repetitive work. Many software requirement manuals (SRS) are poorly written. The quality of any product requires the quality assurance of its original materials. Poor software requirement specifications cannot produce good software. Unfortunately, almost no developers have received education related to abstract, analysis, documentation, and quality control of requirements. In addition, there are not many good requirements to learn from, in part because few projects can find a good reference. Other reasons are that the company is unwilling to put its product manuals in the public area. This article describes the characteristics of high-quality requirements ). We will use these points of view to examine some flawed needs and recompile them with pain points. In addition, I will talk about some tips on how to compile the requirements. You may want to evaluate your engineering needs through these quality standards. It may be too late for revision, but you will learn something useful and help your team write better requirements in the next compilation. Do not expect to write out an SRS that reflects all the features required. No matter how detailed, analyzed, commented, or optimized your needs are, they cannot be perfect. However, if you keep these features in mind, you will write out better requirements and produce better products. How can we identify good software requirements from problematic needs? This section describes the six features that the requirement description should reflect. The next section describes the features that the SRS document should possess as a whole. One way to determine whether each requirement has its own characteristics is a formal inspection conducted by the project fund manager with different points of view. Another powerful method is to compile a test example as required before writing the code. The test example can clearly show the product behavior (characteristics) described in the requirement and show defects, redundancy, and ambiguity. Correct: each requirement must accurately describe the features to be delivered. Correctness is based on the source of the requirement, such as a real customer or high-level System Requirement Specification. The conflict between a software requirement and its corresponding system requirement specification is incorrect (of course, the System Requirement Specification itself may be incorrect ). Only the representative of the user can determine the correctness of the user's requirements, which is why the key of the user or their agent should be included during the check. A check that does not include user requirements will lead to a well-known guess such as "this is meaningless" and "this may be what they mean. Feasibility: each requirement must be achievable in known capabilities, limited systems, and their environments. In order to avoid the feasibility of the requirement, a developer should be involved in the requirement analysis stage, and a marketing personnel should be involved in the abstraction stage. This developer should be able to check what can be done technically, what needs to be paid, or what needs to be weighed against others. Necessity: each requirement should specify what the customer really needs and what needs to comply with external requirements, interfaces or standards. Each requirement comes from the original materials that you acknowledge and have the permission to describe. This is an additional consideration: another way to think of "necessary" is that each requirement originated from a source you recognize as having the authority to specify requirements ). Trace each requirement back to its source, such as use cases, system requirements, rules, or opinions from other users. If you cannot identify the source, you may only need a gold-plated example. Priority: to indicate the key points that should be included in a detailed product version, you need to assign implementation priority to each requirement, feature, or use case. The customer or its agent should have a strong responsibility to establish priority. If all the requirements are considered equally important, the project manager will not be able to play a role when new requirements are caused by budget reduction, plan timeout, or team member departure during development. Priority is used to provide value to the customer, realize relevant costs, and realize associated technical risks. I use three levels of Priority: High Priority indicates that the requirement must be reflected in the next product version. Medium priority indicates that the requirement is required, however, if necessary, we can postpone it to a later product version. Low priority indicates that it is good, but we must realize that it can be abandoned if there is not enough time or resources. It is clear that the readers of a demand statement can only get a unique explanation. Likewise, multiple readers of a demand should reach a consensus. Natural Language can easily lead to ambiguity. Avoid using subjective words that are clear to SRs authors but not clear to readers, such as user-friendly, easy, simple, fast, effective, several art-level, improved, and maximum, minimum. Every write must be concise, simple, and intuitive. Do not use computer terms. The valid method for Fuzzy check includes formal check of the requirement specification, write test as required, and create a user's hypothesis to explain the expected characteristics of a specific part of the product. Verifiable: Check whether you can make a test plan or other verification methods, such as inspection and validation, to determine whether each requirement in the product is implemented correctly. If the requirement is not verifiable, it is determined whether the requirement is implemented correctly. Requirements are inconsistent, not feasible, and cannot be confirmed if they are not clear. Any requirement is unverifiable if the product will support anything. Features of high-quality Requirement Description a complete SRS not only includes a long list of functional requirements, but also external interface descriptions and non-functional requirements such as quality attributes and expected performance. The following describes some features of high-quality SRS. Complete: the required information and requirements should not be omitted. Integrity is also a requirement. It is difficult to find the missing information because it does not exist at all. In SRS, the requirement is organized in a hierarchical Directory, which will help reviewers understand the structure of the functional description so that they can easily point out the missing items. When abstract requirements, you pay too much attention to the user's business compared with system functions, which will lead to insufficient requirements in the demand overview and introduction that are not really necessary. In demand abstraction, the application case method will play a very good role. The graphic analysis model that can view requirements from different perspectives can also check for integrity. If you know that some information is missing, using the TBD (to be determined) standard mark can highlight these defects. When you are building related parts of the product, you can solve all the defects from a given requirement. Consistency: consistency requirements do not conflict with other software requirements or high-level system (business) requirements. Inconsistency in requirements must be solved before development starts. Only after investigation can we determine which ones are correct. Exercise caution when modifying requirements. If only the modified part is approved and the modification part is not approved, it may lead to inconsistency. Modifyable: You must be able to validate SRS when the requirements for each requirement are modified or their historical changes are maintained. That is to say, each requirement must be individually labeled and separately described with respect to other requirements for easy and clear access. Good organization makes requirements easy to modify, such as grouping related requirements, creating directory tables, indexing, and pre-and post-reference (photos ). Trackable: You should be able to align a software with its original materials, such as advanced system requirements, use cases, and user proposals. The software requirements and design elements and source code can also be used to construct a test to meet and verify the requirements. Traceable requirements should be independently labeled, carefully written, and structured. They should not be too large, rather than a narrative text or announcement list. The review of demand quality describes the characteristics of demand quality in theory, but what does a good requirement look like? To make it more practical, let's make a small exercise. Below are several requirements selected from the actual project. Based on the above quality standards, each requirement is evaluated to see what problems are there and then rewritten in a better way. I will give my own analysis and improvement suggestions for each example. You are also welcome to give different opinions. What I take advantage of is that I know the source of each requirement. Because you and I are not real customers, we can only guess the intention of each requirement. Example 1: the requirement that "the product should provide status information in a normal period of no less than 60 seconds" is incomplete: what is the status information and how to display it to the user. This requirement is vague. What part of the product are we talking about? Is the status information interval assumed to be no less than 60 seconds ?, What's more, a new status information is displayed every 10 years? Maybe the intention is that the message interval should not exceed 60 seconds. Is 1 millisecond too short? The word "every" leads to uncertainty. The consequence of the problem is that the demand is unverifiable. One way to make up for the defects and rewrite the requirements: 1. Status information 1.1 Background task manager has a 60-second interval with an error not greater than 10 seconds, status information 1.2 is displayed at a specified position on the user interface. If the background process is normal, the percentage of completed tasks should be displayed, related information should be displayed. 1.4 background task errors should be displayed. In order to test and track the tasks separately, I divided them into multiple requirements. If you concatenate several requirements in a section, it is easy to miss one during construction and testing. Example 2. "The product should be instantly switched between display and hidden non-printable characters." The computer cannot do anything in an instant, so this requirement is not feasible. Its integrity is manifested in the absence of a declared condition for triggering status switching. Must the software change itself under certain conditions? Or do the user perform some actions to imitate the changes? What's more, how long is the display range changed in the document: the selected text, the entire document, or others? This is also a fuzzy problem. Do unprintable words match the hidden characters? Or some property flag or some control characters? The consequence of the problem is that the demand is unverifiable. The requirement for writing like this may be better: "users can switch between displaying and hiding all HTML tags in an edited document activated by a specific trigger condition ". It is clear now that the characters cannot be printed as HTML tags. Because no trigger conditions are defined, the requirement is not binding on the design. Only when the trigger condition is selected by the designer can you write the correct operations triggered by test verification. Example 3: "The HTML analyzer can generate HTML Tag error reports to help HTML reporters quickly solve errors ". The word "quick" makes it fuzzy, and the definition of the error report is complete. I don't know how to verify this requirement. Find an HTML handler to see if the error can be quickly solved based on the error report? Try this: "The HTML analyzer can generate an error Report, which contains HTML text and line numbers and descriptions of errors in the analyzed file. If there are no errors, no error reports will be generated ". Now we know what will be added to the error report, but what the error report looks like is left by the designer. An exception is also specified: If no error is found, no error report is generated. Example 4: "If possible, the supervisor number should pass online verification, rather than the master number list verification ". Desperate. What is "if possible": if technically feasible? Can I obtain the number list of the master supervisor online? Avoid such inaccurate words as "should. Whether the customer needs this function or not. I have read some Requirement documents that use nuances such as: Yes, yes, should/will, and other words to describe the priority. However, I prefer to use "application" to clearly describe the intention of the requirement and specify the priority. This is modified: The system should verify the entered supervisor number without going through the online master-all-host number list. If no supervisor number is found in the list, an error message is displayed and the command is not accepted. The difficulty that developers will encounter in understanding the poor requirements that have been completed is that developers and customers will have a heated debate before reviewing the requirements and reaching consensus. It is not easy to check the large requirement documents in detail. I know someone has done it, and every minute they spend on checking is worth it. Compared with the development phase and users' complaints, fixing defects in this phase is cheap. There is no formula for compiling quality requirements guidelines to compile excellent requirements. This requires a lot of experience and learning from the problems you have found in past documents. Strictly follow these guidelines when organizing software requirements documents. Sentences and paragraphs must be short. Adopt the active tone. Use Correct syntax, spelling, and punctuation. To use terminology, you must maintain consistency and define them in the glossary or data dictionary to check whether the requirements are effectively defined. You can refer to the developer's point of view. Add the phrase "when you finish searching for me" to the end of the document to see if you are nervous. In other words, do you need additional explanations from the SRS compiler to help developers better understand the requirements for ease of design and implementation? If yes, the requirements need to be refined before continuing to work. The requirement writers should also work hard to correctly grasp the degree of refinement. Avoid long descriptive paragraphs that contain multiple requirements. It is helpful to note that you need to write an independent testable code. If you think that a small part of the test can verify that a requirement is correct, it has been refined correctly. If you think of a variety of different types of tests, several requirements may have been squeezed together and need to be split up. A single requirement is merged by paying close attention to multiple requirements. The connector "and"/"or" in a requirement suggest merging several requirements. Do not use "and"/"or" in a requirement ". The details of the entire document must be consistent. I have seen many different requirements. For example, "the valid red color code should be r" and "the valid Green color code should be G" can be separated with scattered demands, "The product should be able to respond to instructions from voice editing" should serve as a sub-system and should not serve as a single functional requirement. Avoid too many representations in SRS. Adding the same requirements in multiple locations makes the document easier to read, but it also makes it difficult to maintain the document. Multiple documents must be updated at the same time to avoid inconsistency. If you follow these guidelines, you will be able to review requirements formally or informal as early as possible. These requirements will become the cornerstone of product construction, system testing, and final customer satisfaction. Remember that without a high quality requirement, software is like a box of chocolate, and you never know that you will