UNIT 4 DOCUMENTATION OF REQUIREMENTS Flashcards
What are the 4 steps to systematically document requirements?
- Determination of purpose and target group
- Selection of the detail level and documentation form
- Documentation of requirements
- Checking whether documentation still fits the purpose and target group
Explain the determination of purpose and target group in the documentation phase of RE.
The purpose and the target group must be determined before the documentation is created. Depending on the current project situation, the relevant target group and the specific purpose of the documentation can vary. Typical goals for requirements documentation are as follows:
* Communication support for the stakeholders involved is needed, for example, when requirements need to be clarified and prioritized, or when the identified requirements must be handed over to the architects and developers for implementation.
* A knowledge repository and reference for decisions and definitions is needed so that the results of the original requirements elicitation can still be consulted after commissioning, and for maintenance and further development activities.
* Statements and clarification must be binding in case of dispute. In case of misunderstanding or ambiguity, there should be a binding document that is recognized by all sides as a common agreement.
By defining the purpose and target group of the documentation, the requirements engineer obtains clarity about the use of the documentation. In this way, they can ensure that the documentation is aligned with the purpose and knowledge of the target audience. The requirements documentation can therefore be adapted to the actual requirements in terms of content, scope, and documentation form. For example, a different presentation may be used for coordination with a specialist department than for coordination with top
management, which, in turn, may differ from the documentation for knowledge transfer to the development team.
Typical risks in the practical handling of documented requirements are, for example, stakeholders who do not understand the documentation form used, but do not admit this.
If, for example, specialist departments are confronted with very detailed software models in order to coordinate requirements for the system, there is a risk of misunderstandings.
Another risk is the danger that important, and possibly not yet agreed upon, requirements are hidden in large documents with several hundred pages and are simply overlooked during the audit.
In an Agile software project, the last opportunity to verify the correctness and completeness of the requirements is when the goal is set at the beginning of a sprint. The team, together with the process owners and some key users, then go through the requirements that must be realized and accepted at the end of the sprint.
What are the different levels of detail a requirement can have?
Since requirements can be related to each other in a refinement hierarchy, they can be assigned to one of four different levels of detail. The requirements at each level describe the system completely, either very abstractly or in a more refined way.
Usually, there are requirements at all four levels of detail for a system. The levels establish how completely the requirements are determined and documented. With this theoretical
view, the requirements engineer can consciously decide which requirements in which level they should elicit next, or at which points they want to forego completeness or refinement.
A specification with the same level of detail in all areas indicates a waste of resources or a lack of detail. Certain issues within a specification are more descriptive than others.
Describe the Selection of the Level of Detail and Form of Documentation.
Since the documented requirements are read and understood by different groups of people depending on their use, it is important to take the prior knowledge and interests of the respective stakeholders into account. With regard to the level of detail of the documentation, a decision must be made as to whether an overview is sufficient (e.g., for communication with top management) or whether a detailed presentation of the requirements is needed (e.g., for estimating the effort and duration of implementation).
After determining the required level of detail, the necessary forms of documentation are defined. Not all requirements should have the same final maturity level, and they do not have to be at the same level at the same time in the project. Typical, widely used documentation forms for requirements are software models, prototypes, sketches, tables, and text.
Describe the actual documentation of requirements in the documentation phase.
The requirements can now be documented in a form suitable for the purpose and target group. Changes to the requirements in drafts (e.g., deletion of requirements) or in detail (e.g., minor change) are commonplace in a project. It is advisable to log the changes with the date and reason for the change to enable traceability. Changes usually result in collateral changes to related requirements. Finding them is not always easy, so it is recommended to document relationships between requirements.
How would one check whether documentation still fits purpose and target group during the documentation phase?
Since the concrete documentation can take a long time, and the requirements can change among stakeholders as they continue to deal with the subject matter, it is important to regularly review whether both are still appropriate for the current purpose and goal. It is common, in practice, for the documentation team to lose sight of the objective or lose track of the changes. In this case, it may become necessary to adapt the documentation to
the changed conditions.
What are the main elements of requirements documents for documentation structure?
- Project vision
- Overview level
- Detailed requirements
- Glossary
Describe the Project Vision element of requirements documents.
At the beginning of a project, the client’s specifications and requirements must be determined, documented, and agreed upon. Starting with the initial project idea, the client’s requirements, goals, and expectations are identified and defined step by step. Formulating the project vision in text helps the project team to develop a common understanding of the project vision and communicate with the stakeholders. In the first workshop of the project, it is recommended to formulate the project vision or goal as a text of half an A4 page (approximately 1,600 characters) and agree upon it with all stakeholders.
The project vision obtained should be the first section of a requirements document. It should answer the following questions:
* What is the goal or purpose of the project, i.e., what will be achieved?
* What is the motivation for the project, i.e., why does this project exist?
* What is the definition of the level of requirements described in the document, ideally together with the purpose and target group of the document?
The project vision is an introduction and guide to the contents of the document, as well as an anchor and pick-up point for workshops and meetings with the stakeholders. Furthermore, it can be used for the final check to establish whether the content and form still fit the purpose and target group.
Describe the Overview Level element of requirements documents.
The project vision is followed by the overview level, which is used for the technical and functional classification of the application. After reading the overview level, the reader
should be able to obtain a general overview of the main system functions, technical interfaces, users, and classification in the system landscape. The following should be considered:
* location of the system in the business process landscape, i.e., a brief description of which business processes and functions are supported by the system
* embedding of the system in the information technology (IT) landscape of the organization, so it is possible to classify the system compared to other IT systems
* brief description of the most important system function so that the reader can gain an overview of the individual system functions, e.g., with use cases
* technical interfaces to other systems, so all involved parties are aware of the technical dependencies, and technical integration can be started at an early stage
* brief description of the roles that will actively work with the system, so it is clear which stakeholders must be actively involved in requirements elicitation
Describe the Detailed Requirements element of requirements documents.
Each system function described in the overview must be documented in detail before implementation. Therefore, the section with the detailed requirements is usually also the largest in the requirements document. Each system function should be described briefly so that the reader has an overview. Let’s assume that, for an online store, the important system functions “Add items to inventory,” “Search goods,” “Buy items,” and “Send newsletter” have been identified. Each of these functions must have a section in the detailed requirements documentation.
Typically, a system function is made up of various sub-functions. For example, the “Buy item” function of an online store can be composed of the sub-functions “Add item to shopping cart,” “Pay item,” “Shipping processing,” and “Rating.” These sub-functions are documented within the system function section. For each sub-function, all of the information that the development team needs to start implementing the system is compiled before the implementation starts. In particular, this includes all relevant functional requirements, quality requirements, and constraints. These requirements can be documented using text, bulleted lists, tables, functional models, references to external documents, and screenshots of prototypes.
In addition to the documentation of the individual system functions, it is often useful to create a comprehensive domain-oriented object model. The object model can be used to describe and document the domain-oriented relationships and properties of business objects.
Describe the Glossary element of requirements documents.
In every company, there are industry- or company-specific terms that may not be known by all project participants (e.g., requirements engineers or service providers). Abbreviations in particular require binding definitions in a glossary. Confusion can also be caused by common verbs that may have a special meaning in the project environment, for example, “to archive.” What does it mean when a document is archived? What access does a user have, and how long does it take to gain access to the document? What happens when changes become necessary? The following is a list of tips for building the glossary:
* Sort the defined terms alphabetically.
* Define technical terms to be used in the requirements. If available, list synonyms or related terms that may have a different meaning.
* Define verbs to prevent misunderstandings if they are not otherwise defined or explained in the specification.
* Describe adjectives, such as “fast.”
* Use legally binding modal verbs and explain their meaning.
* Define requirements related to roles by describing tasks and responsibilities
What are the different types of documentation?
Text and tables, user stories, epics, sketches and simple graphics, models, GUI prototypes, mixed forms of documentation, and some other types of documentation formulation and formalization.
Describe the text and tables type of documentation.
The simplest forms of documenting requirements with text are formulating written text and listing individual requirements. Tables, on the other hand, help to structure the requirements. They can be used, for example, to clearly present value ranges, concrete properties, and aspects that are technically different but structurally similar.
The advantages of documentation in the form of text and tables lie in their ease of use. Neither documenting nor reading documentation requires any additional learning. In addition, both are versatile because they can describe all types of requirements. The disadvantage, however, is the room for interpretation and inaccuracies in the formulation of requirements.
In some requirement specifications, only the positive cases are described. It is also important to describe the behavior of a system when something goes wrong. These negative cases are in the majority, and it is sometimes hard to think of all the circumstances in which things can go wrong and create test cases for them.
We can start with a roughly structured specification and then move to a detailed structured specification in
which the extensions are identified by hierarchical numbering. A semiformal specification with a strict outline is shown, which can be reused as a template for other requirements. A formal specification, which looks like a piece of program code, is very compact (without the same amount of detailed information), but it is not understood by stakeholders without programming skills.
The disadvantages of documentation exclusively in text form are so serious in practice that other forms of documentation have been established in addition to text.
Describe the User Story type of documentation.
User stories are a popular technique used in Agile. The logic behind user stories is simple, and if some basic guidelines are followed correctly, they can be quite effective. However,
this simplicity only goes so far, and user stories need to be complemented by a degree of rigor to benefit from this technique. A well-written user story scribbled on a sticky note or
card has the following form:
As a <role>, I want to <function>, so that <benefit>.
The user story defines who, what, and why. The user story should also contain a first estimation of the business value of the described function and the effort required to realize it.
The realization effort in Agile projects is roughly estimated using the “T-shirt sizing” technique. The relative effort at the beginning of a project is just a way to say that one task may take four times longer than another. During the project, when reliable data about the realization effort (in, e.g., hours or days) are available, then the effort of the other realization tasks can be determined using the rule of three.
User stories should summarize key information about a requirement. Therefore, other supporting information or documentation usually needs to be referenced in order to fully
understand all of the detail behind a user story. This supporting information could have many forms, e.g., a detailed written specification; figures; models; or reference material,
such as standards and guidelines. These cross references would be included as part of the user story.
People sometimes refer to epics as coarse-grained user stories that break down into fine-grained user stories. lf the user story clearly shows the information regarding effort and value, it can make prioritization easier. A high-value feature with a low amount of effort will stand out as a priority. User stories evolve as understanding increases. This is why, in an Agile environment, there is little desire to define them in detail in the early stages of a project.</benefit></function></role>
Describe the Epic type of documentation.
Customer requirements in an early development stage can be quite large or vague. This has given rise to a different type of user story, known as an epic. In effect, this is a high-
level or “super-user” story that will, over time, be broken down into user stories at a level of granularity with which the delivery teams can work. One way to derive the user stories is to walk through the process relating to the epic. Epics can appear on a product backlog, but they do not appear towards the top, as they are not written in sufficient detail.
