Making it easy for you to find requirements information is a key purpose of IBM® Rational® Requirements Composer. This assists with requirements validation and discussion, as well as reuse and contextual understanding. Methods for achieving this include folders, saved filters, tagging, attributes, and collections (see Figure 1).
Figure 1. Filters by collection, folder, tags, attribute can be saved
The purpose of the folder structure is to make it easy for authors to find, create, and edit requirement artifacts while, at the same time, making it easy for reviewers to find and comment on or formally review requirements. The key is to consider the audience.
The folder structure provides a logical storage mechanism for projects. Searching and browsing can also be accomplished through the various tabs, links, tags, filters, and search dialog.
When using the interface, business stakeholders need to understand at a glance how to navigate, comment, or formally review the project. If stakeholders are expected to navigate the folder structure, it can help to use language that the business people understand, rather than technical language.
While most stakeholders use the interface as expected—viewing artifacts and making comments— some take another approach. Stakeholders might prefer to print the artifacts and comment later, either by using the interface or in some other way.
Approaches to folder structure
Several approaches are described here to provide ideas. Many other approaches can be taken. The most typical, and the approach provided in Rational Requirements Composer, is to use artifact types. The structure can be modified by project administrators at any time after it is created. The recommendation is to set the structure in the beginning and to make minor updates as needed.
Folder structure by artifact type
This example uses artifact types to determine folder names. Due to expectations of collaboration with business stakeholders, we use business wording to describe areas as opposed to technical terminology:
- Vision statement or business case (why you are building the system)
- Business process diagram
- What the system does (use cases or user stories)
- Usability, reliability, performance, supportability, scalability (nonfunctional requirements or technical stories)
- Pre-project documentation
- Workshop notes
- Release documentation
On many projects, it is useful to pull in background information from the early workshops that planted seeds for the project. These artifacts might take the form of photo or image files, documents, or presentations that document the business case. Pre-project documentation, background information, or workshop notes folders could hold this information
Folder structure to reflect a particular approach or method
Many agile projects take a lightweight approach to documentation, including requirements artifacts. Folders need to reflect this and typically include:
- Vision or business case
- User Stories
- Reference material
A similar approach to using folders by artifact type would be appropriate for many methods, including ones with iterative, incremental, and waterfall-style lifecycles.
Folder structure by functional area of the system or business area
Each functional area (order processing or new business, for example) can include a different set of people leading or working on it. In this scenario, it might be preferable to set up a folder for each functional area, with subfolders containing that area's artifacts.
When a project includes multiple business areas that collaborate on specific requirements (sales, marketing, and accounting, for example), it might be preferable to separate the business areas of concern so that it’s easy for Reviewer stakeholders to follow. In this case, a folder is created for each business area, and subfolders are created for artifacts for them to review.
Table 1. Example of folder structure by functional area
|Project reuse library||Reusable bits, e.g., user interface (UI) parts, glossary|
|System administration||Requirements for the system administration part of the project|
|Reporting||Requirements for the reporting portion of the project|
|Functional area n||Requirements for another functional area (n)|
|Functional area n+1||Requirements for another functional area (n+1)|
|Background information||Information that provides background to the project in general. This could include items such as a Statement of Work, a set of slides that depict the proposed solution, a photo of a whiteboard diagram, and so on.|
A tag is a keyword or term assigned to any artifact or requirement. It is later used to search or filter artifacts and requirements within and across projects. Tagging across many different requirements and artifact types gives you the flexibility to group a diverse range of artifacts and requirements together.
There are shared and personal tags:
- Shared tags are maintained in upload and download and can be used in saved filter queries.
- Personal tags are just used for filtering in a person’s local area.
Tagging is typically used in conjunction with folders and can also be used as an alternative approach.
Tagging is useful in conjunction with filters, because specific queries can be preconfigured for particular business users to view artifacts of interest. For example, if the folder structure is arranged by artifact type, tagging by business area across all folders can be a very useful approach. This makes it easier for everyone to locate relevant information.
A very useful application of tagging is to assign a tag to show that a requirement is part of a release (Release 1, for instance). When these requirements are filtered, they can be added to a collection. This is particularly useful when using Rational Requirements Composer in conjunction with IBM Rational Team Concert™ because plan items can be automatically created based on the requirements in this collection.
In theory, there are several approaches to tagging:
- Ad hoc policy
- Creators use tags in any way that they find helpful.
- Informal policy
- This typical includes some structure and guidance: Certain tags are suggested, such as department names. Flexibility for social bookmarking is also allowed.
Formal classification structure
Guidelines and best practices
Typically, tags are used to help search and browse in Rational Requirements Composer, rather than in managing requirements.
Tags are useful when they help people collaborate better among roles, teams, and geographies.
Tags can be especially useful when they are relevant across multiple types of artifact.
Encourage informal shared bookmarking, because it makes tool use more flexible and artifacts easier to find for a broad range of users.
Tagging is favored over a deep sub-folder hierarchy, because deep hierarchies can be cumbersome to navigate.
Seeding a project with shared tags from the beginning encourages tag use.
Attribute groups are generally preferred for more formal classifications.
Attributes specify characteristics about a requirement or artifact. Attribute groups provide a way to reuse attributes across specific project artifacts and requirements. Attributes are used for querying and ordering groups of requirements and artifacts.
File name, date, user, artifact type, and lifecycle status are default attributes available on artifacts for filtering.
Specifically defining attributes (by business priority, stability, and difficulty, for example) results in additional filtering options. A good way to decide which attributes and attribute groups to use is to think about which reports or filters could be used to answer expected questions.
Requirements use attribute groups to show their requirement types. A requirement can be associated with only one attribute group (see Table 2). This is selected either as part of the requirements creation, using the wizard, or added after creation.
File name, date, user, and lifecycle status are default attributes available on requirements for filtering.
Attribute us might be affected by your choice of requirements management tool and how any existing IBM® Rational® DOORS® or IBM® Rational® RequisitePro® projects are already configured.
Table 2. Example of an attribute group definition
|Attribute group||Attribute||Attribute values|
|Storyboard attribute group||State|| In progress (default)|
|Test ranking|| Testable|
|Architectural review|| Reviewed|
|Complexity to implement|| Complex|
|Contact person|| Kirk|
Table 3. Example of a table to show an attribute group definition
|Attribute groups||Feature||Use case||Supplemental||Storyboard||Origin|
|User interface part||X||X|
|Business process diagram||X|
|User interface Sketch||X|
|Use case diagram||X|
*Resource wrapper is for all external artifacts that have been loaded into the repository, such as JPG files of whiteboard sessions.
Saving shared filters makes it easier for people to adopt filters. By applying a preconfigured filter, the user sees a shorter list of artifacts or requirements. As a result, they are less likely to be overwhelmed with information that doesn’t pertain to them.
One point of Rational Requirements Composer filters is to make finding groups of requirements and artifacts easy. They work in conjunction with the data defined using tags, attribute groups and IBM® Rational® C/ALM (Collaborative ALM) links to provide a means of rapidly reduces the amount of information a user sees. Rational Requirements Composer provides one requirements repository for all stakeholders, containing one version of the truth with a high level of transparency, so making it easy to find relevant information and artifacts is vital for all users within and across projects. Filters make this possible.
These might be shared filters that everyone can use or personal filters that an author creates for private use. It is best that some initial shared filters are provided on the team's behalf and, in particular, on the business stakeholders’ behalf. Personal filters can be specific, saved views or ad hoc filters that are used often. The folder structure is a special case of public filtering, as are tags.
Ad hoc filtering capabilities
There are many ways available for filtering in Rational Requirements Composer. Some filters work only if you take an action, such as tagging artifacts or setting attribute values on requirements. Other filtering capabilities will work as long as you have artifacts or requirements available to list. These are based on file name, on location in the folder structure, on the name of the user who created the artifact, on the date, or on artifact type.
Any filter can be saved as a shared filter for all team members to reuse.
If attribute values about requirements are set, such as “Priority” and “Difficulty,” a filter based on the attributes could be created and saved as a group identified for an iteration. For example, all high-priority and high-difficulty requirements could be saved for Iteration 1. Filtering on an attribute such as Status, combined with an Iteration filter or attribute, is useful for identifying how much work needs to be completed for the next iteration.
Certain filters might be useful for the entire team. Maybe a filter on artifact type, such as storyboards and date, over the last month would help everyone find all of the storyboards created in the past month.
The Stakeholder Collaboration Strategy might contain details of preconfigured saved shared filters.
A collection is a mechanism to group artifacts and requirements. Collections can be used to provide an easy way to view a grouping of artifacts or requirements.
Collections group together a range of artifacts or requirements, or both, for targeted reviews for particular stakeholders, either as a formal or an informal review. Snapshots can also be included within a collection for review.
They can also help establish a baseline for a group of functionality for a particular iteration.
You can create multiple Plan items by using Rational Team Concert rich-text client, basing them on the requirements included in a collection, and establish links from the Plan items back to the requirements. This is typically an activity performed by a team lead or project manager.
You can create test cases in bulk by using the IBM® Rational® Quality Manager client from requirements included in a collection, and establish links from test cases back to requirements. This is typically performed by a test lead.
Although planning for collections might start from the beginning of the project, collections are created when artifacts start to take shape and the team is ready (or preparing) for reviewers to use them for informal or formal reviews, linking to test plans, or creating work items. Typically, these would be viewed by clicking the Collections tab on the project dashboard. It can also be helpful to create a folder for collections.
The Stakeholder Collaboration Strategy can contain any policy regarding collection use.
Fast View, Search, and Advanced Search
Access to Fast Views can be set up with a button that is typically at the left of the screen and can also be anchored on sidebar on the right. This can be especially useful for properties and outline views. Outline views are especially useful for UI sketch editing.
Advanced Search can also be used to search across multiple projects.
Table 4 summarizes the various techniques for organizing the project and repository space. Review and approval are considered in more detail later in the series.
Table 4. Summary of key techniques for organizing the project and repository space
|Type of organization||Description|
|Folders||Folders are used to create a fixed hierarchical project structure and to create a fundamental project framework for storing requirements, artifacts and collections. This can be used in conjunction with tags.|
|Tags||Tags are a more informal way to classify requirements, collections and artifacts. They have the advantage of working across folders and projects so they are useful for a broad classification. It is also possible to tag items in bulk.|
|Attribute Groups||Attribute groups provide a more formal classification structure, including attribute names, values and default value. They can be applied across requirements and artifacts and can also map to requirement types. They are useful for both requirements management and an additional, more formal, filtering mechanism.|
|Filters|| Filters can be used to view various artifacts or requirements by folder, tag or attribute values.|
All the meta-data above (folders, tags and attribute groups) provides the input for filters which allows users to find and access a subset of the repository’s relevant artifacts and requirements.
|Collections||Collections are used to group artifacts and requirements. A collections tab on the project dashboard provides a list of collections for the project. These are useful for a number of purposes from targeting reviews to C/ALM integrations.|
|Snapshots||A project snapshot is a capture of an entire project at a specific moment in time. It includes all artifacts, folder trees, and the shared tag list.|
|Review and Approvals|| A review is a set of artifacts that you create to be reviewed by specific team members. The review follows a lifecycle that changes as participants complete the review. |
You can create a review for individual artifacts that you select or you can create a review of a collection (see Collaboration Strategy).
Ultimately, the decision as to exactly how to adopt these techniques will be determined by individual teams. The underlying philosophy to adoption is that doing so will improve collaboration with stakeholders by making information easier to find.
This article considered ways to organize the project and repository space. It laid the foundation for the next article in which content creation is addressed. The next article discusses the approach to selecting artifacts, creating requirements and linking.
The authors thank Robin Bater, Rational Requirements Definition and Management Community of Practice Architect, and Daniel Moul, Market Management Offering Manager for Requirements Definition and Management, for their technical reviews and encouragement.
- Learn more on Jazz.net:
- For an introduction, read Capturing Architectural Requirements by Peter Eeles (IBM developerWorks, November 2005).
- Start here to learn more about Rational Requirements Composer on IBM.com:
- Learn about other applications in the IBM Rational Software Delivery Platform, including collaboration tools for parallel development and geographically dispersed teams, plus specialized software for architecture management, asset management, change and release management, integrated requirements management, process and portfolio management, and quality management. You can find product manuals, installation guides, and other documentation in the IBM Rational Online Documentation Center.
- Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
- Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Some of the "Getting Started" courses are available free of charge.
- Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
- Browse the technology bookstore for books on these and other technical topics.
Get products and technologies
- Download IBM Rational Requirements Composer and try it, free.
- Download trial versions of other IBM Rational software.
- Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Tivoli®, and WebSphere®.
- Join the discussion in the Rational Requirements Composer forum about all aspects of requirements definition, including both general, tool-independent concepts and tool-specific information.
- Check out developerWorks blogs and get involved in the developerWorks community.