How to write high quality "Software Demand Manual" Original: Karl E Wieger, Process Impact May 21, 2003 Your project should have a good start. A group should lead the customer to enter the demand inspiration phase and you want to write a software demand manual. This description is somewhat big, but the customer will pay much attention, so it must be agreed. Now you are designing a feature that has discovered some problems with demand. You can use a variety of different ways to explain the requirements 15; demand 9 instructions are just in contrast to demand 21, which one is believed? Demand 24 is very vague, you don't understand what it means; you have to spend an hour and 2 developers discuss demand 30, just because you have your own understanding; and the only customer who can clarify these issues Give you a reply. You are forced to break the meaning of many needs, and you can expect that if you are wrong, you have to do a lot of repetition. Many Software Demand Manual (SRS) is very bad. The quality of any product requires the quality assurance of its original material, and the bad software demand manual is impossible to produce excellent software. Unfortunately, there is almost no developer's education related to demand, analysis, documentation, quality inspection. Moreover, there is not much good demand can learn from learning. In part, there are very few projects to find a good reference. Other reasons are that the company is reluctant to put its product manual in public areas. This article describes several characteristics (characteristics) of high quality needs narratives and descriptions. We will check some of the defective demands with these perspectives and rewrite the pain. And I talk about how to write a good demand. You may want to evaluate your project needs through these quality standards. For revisions, you may be late, but you will learn some useful things and help your team write better next time. Do not expect SRS that can be written in all features that can reflect demand. No matter how you refine, analyze, comments, and optimize demand, it is impossible to perfect. However, if you keep in mind these features, you will write better demand and produce better products. High quality needs narrative characteristics How do we distinguish between some problematic needs? This section will introduce six characteristics that should be reflected in the description of the requirements, and the next section will introduce the characteristics of the SRS documentation. It is a way to determine if each requirement has the characteristics that should have a regular examination made by the engineering fund managers holding different perspectives. Another powerful method is to write test examples based on demand prior to writing code. The test example can clearly show the product behavior (characteristics) described in the demand, which can show defects, redundancy, and vague. Correct: Each requirement must accurately describe the functions to be delivered. The correctness is based on the source of demand, such as real customers or high-level system requirements instructions. A software requirement is incorrect with its corresponding system requirements instructions (of course, the system needs manual may be incorrect). Only the user's representative can determine the correctness of the user's needs, which is why it is the key to them or their agents when checking the needs. Does not include the user's demand inspection, which will lead to developers: "This is meaningless", "this may be their meaning", etc., well-known guess. Feasibility: Every need must be realized in known capabilities, limited systems and their environments. In order to avoid the incompetence of demand, there should be a developer's participation in the demand analysis phase, and there should be market staff to participate in the abstract stage. This developer should be able to check what can be done in technology, which needs additional or other weighing. Necessity: Each requirement should be made what customers do need, what should be in line with external demand, interface or standard.
Each requirement stems from the original information you recognized, with the right to explain the needs of the demand, which is the necessary additional situation (translation, this sentence is not obvious, please refer to the original text: another way to think of "Necessary" is that each request, A Source You Recognize As Having The Authority To Specify Requirements. Tracking each requirement to retroactive, such as use cases, system requirements, regulations, or comments from other users. If you can't identify the place, it may be just a gold-plated example, no real must. Priority: In order to indicate which points should be included in a detailed product version, you need to assign a priority for each requirement, feature, or use case. Customers or their agents should have a strong responsibility to establish priority. If all the needs are considered equally important, the project manager will not function as the budget cut, the planning timeout or group members will cause new demands. The role of priority is to provide the value of the customer, the relevant fees realized, and achieve the associated technical risks. I am using three levels of priority: High priority indicates that demand must be reflected in the next product version, the priority is required, but if you need to postpone some product versions, low priority shows It is very good, but we must realize that if there is no sufficient time or resources, it can be given away. Clear: Readers in demand should only be explained from them, and like, multiple readers of a requirement should also reach a consensus. The natural language is extremely easy to cause embarrassment. To avoid some subjective vocabulary for SRS authors but unclear for readers, such as: user friendliness, easy, simple, fast, effective, several, art-grade, improved, maximum, minimum, etc. Every time you write a language that needs to be simple, simple, intuitively, do not use computer terms. Checking the demand blurring a regular inspection of the demand manual, writing tests, establishing a user's imaginary to illustrate a particular part of the product. It can be confirmed: See if you can make a test plan or other verification method, such as checking and empirical, to determine if each requirement is correct in the product. If the demand is invalidated, the decision demand is not a correct implementation. It is inconsistent between demand, it is not feasible, it can not be confirmed. Any requirement if the product will support what is supported. Features of High Quality Demand Instructions A complete SRS is not only a list of long functional requirements, but also an external interface description and some non-functional requirements such as quality properties, desired performance. Some of the characteristics of high quality SRS are described below. Complete: Should not miss the requirements and necessary information. Integrity is also a need to have. It is difficult to find that the lack of information is difficult because it does not exist. The demand will be organized in a hierarchical directory in SRS to help reviewers understand the structure of functional description, so that they can easily point out lost things. When demand is abstract, relatively much attention to the user's business, will lead to the global view and introduction of the demand, not the truly necessary demand. On demand abstraction, the application case method will play a good role. The graphical analysis model that can be viewed from different angles can also check the incompleteness.
If you know that some information is missing, use the TBD (To BE DETERMINED) standard flag to highlight these defects, when you build the relevant part of the product, you can set all the defects from a given demand. Consistency: Consistency requires no conflict in other software needs or high-end systems (commercial) needs. The inconsistency in the demand must be resolved before the development begins. Only through research can determine which is correct. Be careful when modifying the demand, if only the modified part is verified, it may cause inconsistency. Modification: When each requirement is required to modify or maintain its history change, you must be able to verify the SRS. That is to say, each requirement must have its separate indication and separate instructions relative to other needs, which will be readily available. Through good organizations, demand can be easily modified, such as packets related to the relevant requirements, index, and front-rear reference (photo). Tracking: You should be able to correspond to its original materials, such as advanced system requirements, use cases, users's proposals, and so on. It is also possible to correspond to design elements, source code, and tests for constructive implementation and verification requirements. Trackable requirements should have independent marking, fine and structured writing, should not be too large, and should not be a narrative text and a list of bills. The description of the quality of demand quality is very good in theory, but what is a good demand looks like? In order to embody more practical, we do a small practice. Here are a few demands elected from the actual project, based on the above quality standards, evaluate each need, see what is wrong, then rewrite with a better way. I will make my own analysis and improvement suggestions for each example. You also welcome you to make different insights. What I occupied is just that I know the source of each requirement. Because you are not a real customer, we can only guess the intention of each requirement. example 1. "Product should provide status information in a normal cycle of every 60 seconds" this requirement is incomplete: status information is what, how to display it to the user. This requirement has several vague. Which part we are talking about? The status information interval is really assumed to be no less than 60 seconds? What is the new state information is displayed every 10 years? Perhaps its intention is that the message interval should not exceed 60 seconds, then isn't it too short to 1 millisecond? The word "every" leads to uncertainty. The consequences of the problem are the incomprehensible requirements. Method for compensating for defects, rewriting requirements: 1. Status Information 1.1 Backstage Task Manager Because the error is not more than 10 seconds, the specified location display status information 1.2 if the background The process is processed normally, then the task should be displayed when the task has completed, and the relevant information 1.4 The background task should be displayed. The error message should be displayed in order to test and track, I divide it into multiple needs. . If several needs are connected in series, it is easy to miss one when constructing and tested. Example 2. "The product should instantly display and hide the non-printing word between the computer" computer can not do anything in an instant, so this demand is not practicable. Its incompetent manifestations do not declare the conditions for trigger status. Do you want to change yourself under certain conditions? Or use the user to do some actions in order to imitate the changes? Moreover, how big is the range of changes in the document: Select text, the entire document, or other? This is also a blurred problem. Do you not print the word matching hidden characters? Or some attribute logo or some control characters? The consequences of the problem are the incomprehensible requirements.
It is better to write a need to write demand: "The user can switch between display and hide all HTML tags in a document that is edited by a particular trigger condition. It is very clear now that the non-printing characters are HTML tags. Due to no trigger conditions are not defined, the demand is not binding on the design. Only after the designer selects the trigger condition, you can write the correct operation of the test verification trigger. Example 3. "HTML analyzer can generate HTML tag error reports to help HTML entry quickly resolve errors." The word "fast" makes it blurred, and the definition of the incorrect report is also complete. I don't know, how do you verify this demand. Find a entry that claims to be HTML, see if you can quickly solve the error according to the error report? Try this: "HTML analyzer can generate an error report, the error report contains an error in the HTML text and the line number and the wrong description in the analyzed file. If there is no error, it will not generate an error report." Now we know, what will be added to the error report, but what is wrong with the error report, and the designer decided. We also specified an exception: If there is no error, no error report is generated. Example 4. "If possible, the supervisor number should pass online check, not through the main supervisor list." I am really desperate, what is "if possible": If the technical is feasible? Can the main supervisor number list online? To avoid such undesirable words like "should". Customers need this functionality or not. I have seen some demand instructions, using such as: should, will / will / will describe some word to describe the fine differences of priority. But I prefer to use the intention of the description of the description of "should" to clearly specify the priority. This is a modified: the system should verify the input supervisor number without the list of main master numbers. If the supervisor number is not found in the list, an error message will be displayed or the instruction is not accepted. In the understanding of all completed bad demand, the problem that developers will encounter is that developers will have fierce arguments before reviewing, and have not reached a consensus. Detailed examination of large demand documents is not a relaxed thing. I know someone, and they spend every minute of checking. Compared to the development phase and the user's complaints, the repair defects in this stage is cheap, and the policy of writing quality needs is not formulated. This requires a lot of experience, learning from your problem found in the past documentation. Please strictly follow these guidelines when organizing software requirements documents. Sentences and paragraphs are short. Adopt active tone. Use the correct syntax, spell, punishment. Use the term to maintain consistency, and define them in the gloss or data dictionary to see if demand is valid, can be seen in the development personnel. In the heart, "When you have finished looking for me," this is added to the end of the document, see if you can be nervous. In other words, do you need an additional explanation of SRS's writers to help developers good understanding of demand for design and implementation? If so, demand needs to be refinered before continuing to work. The demand writer must also work hard to properly grasp the degree of refinement. To avoid long narrative paragraphs that contain multiple needs. Help prompt is to write independent testing needs. If you think a small part of tests can verify the correctness of a requirement, then it has been properly refined. If you expect a variety of different types of tests, several requirements may have already squeezed together and need to be removed. Closely pay close attention to multiple needs synthesized a single requirement. Connections in a requirement "and" / "or" recommend several needs mergers. Don't use "and" / "or" in a requirement. Maintain consistency on the details of the document. I have seen that there are inconsistencies before and after multiple demand instructions.
