Documents and the registry
It is convenient to work with requirements both as a document and as an arbitrary set of atomic requirements (using the registry or the requirements list). For example, a technical specification or a particular technical specification can be drawn up as a document. Such documents, however, become large, and they are not implemented as a whole. The registry lets you work only with the subset of atomic requirements you need — estimate them, plan them, and control their implementation.
The document view and the list view of the registry each have their pros and cons:
| Pros | Cons | |
| Requirements document |
Related sections of the document are visible on one screen. A complete description of the task. You can set and check requirements for completeness and consistency. Convenient to approve. You can version them and create Baselines. |
Complex systems consist of thousands of requirements, and working with them through a document becomes impossible. Iterative development assumes that requirements are implemented in parts. Groups of requirements may consist of pieces of the document located in different parts of it — try assembling that into one pile. |
| Requirements registry (list) |
There is no excess of information (requirement text) when you work with requirement attributes or links. You can quickly perform bulk operations: estimation, implementation. It is easy to control Traces to source and derived requirements, and to covering artifacts: test documentation, tests, technical documentation, and so on. |
On an arbitrary set of requirements it is impossible to check the completeness, consistency, and integrity of the documentation and the product. Different requirements are usually related to each other semantically, but that cannot be seen from a single requirement alone — you need the structural links that the document view provides. |
For different documentation and management tasks, choose the most suitable way of working with documents. ALM supports all of them.
Import/export and printing
Load your requirement documents in MS Word, OpenDocument, or Excel format. The application automatically splits them into sections according to the structure defined in the document. Heading styles (Heading 1, Heading 2, and so on) are used to split the document into requirements.
The "Requirements are contained in paragraphs" option lets you import compact requirements (without a title). To do this, make the requirement Caption field optional. The entire paragraph text is placed in the Description field.
Export to external formats
You can export an arbitrary set of requirements, a document, or several documents to external formats. When exporting to MS Word, you can specify a document template (a blank) whose styles will be used during export. This template can contain title pages, which means the export can be placed at any position in the template. Using WYSIWYG editor macros, you can export attributes of the document and of specific requirements, for example export the document name to a specific place in the template.
The list of templates previously used for export can be found in the project settings, in the "Export templates" module. The "Requirements-driven development" process contains an example of exporting documents into a template according to GOST requirements. You can define the format of bulleted and numbered lists yourself; the corresponding fields on the Additional tab of the export template are intended for that.
To re-import documents that stakeholders have changed outside the system, use the export option "Export the source code of UML models and formulas". After import, these objects become editable again, because on export they are converted into images.
To import, open the document and, in the Actions menu, select the corresponding menu item.
If you need to print several sections or a whole document, you can use the browser's built-in printing capabilities:
Kinds of links
Requirements can be linked to other requirements or to other project artifacts.
| Link kind | Purpose |
| Structural, parent-child |
It is convenient to decompose complex requirements into smaller pieces. For a use case, child requirements can be: UI mockups, extension points (alternative scenarios or extending scenarios), and system requirements. Requirements can form a hierarchy, and thereby a document, a specification, or a technical specification. For a quick decomposition of a requirement into its parts, create child requirements from a selected fragment of text:
|
| Cause and effect |
In general, functional requirements are created from business requirements (for example, in the use case format). System requirements are created from functional requirements. These are cause-and-effect links, which let you trace the transition from one level of abstraction to another, and so on down to the program code.
|
| Dependencies |
Some requirements can include the content of other requirements in their text, or refer to other requirements. Such references are called "dependencies" and let you find requirements that other requirements refer to (before modification or deletion).
|
| Coverage | This type of link is established between requirements and other project artifacts: test documentation and technical documentation (user guides). |
Links are created transparently for the user when project artifacts are created from primary, business, or system requirements (for example, using the green buttons or menu items). Links can be edited on the "Traces" tab.
Links can be visualized on a network diagram (on the Links tab):
Traceability between requirements (cause-and-effect links) and between requirements and other project artifacts (coverage) is used in ALM as a tool for maintaining the integrity of project documentation. When a source requirement changes its text, the system marks all derived requirements and coverage with the "Outdated" flag. Outdated requirements and other artifacts are easy to find and update in order to restore the integrity of the link.
Templates
Requirement templates are standard blanks that you can use when documenting requirements. Templates are inserted when you type the # character (hash). If a template is defined as the default template, it is inserted immediately when a requirement is created. Different requirement types can use different default templates. We have already included several common templates in the standard processes, but you can delete them and use your own.
Besides page templates, you can create document templates. For example, this can be a standard document for creating a technical specification or a specification according to the sample adopted in your organization. To create a template, import your blank into ALM or build the structure with the application. In the "Actions" menu, while working with a document, select "Create template". To create a document from a template, use the buttons with their names:
Reuse
Requirements can be reused in several ways.
Move shared requirements into a program of projects. In the subprojects you can reference them or elaborate these shared requirements.
To create a copy of a requirements document in another project, select "Duplicate" in the "Actions" menu while working with the document. In the requirements registry, any subtree or requirement can be copied (duplicated) into the current project or another project using the "Copy" action.
If a requirement is reused in several documents, you can include that requirement in the required section of a document. The operation is available from the context menu of the requirement, and also as a bulk operation in the requirements registry.
If the text of some requirement must be repeated in the text of other requirements, use the WYSIWYG editor's ability to insert the text of another project artifact into the requirement text. This is available from a button on the toolbar or from the context menu in the WYSIWYG editor.
To insert several requirements into another document at once, open the requirements registry and select them with the checkboxes, then use bulk operations to add these requirements to the selected document or to a new one.