Using the Stakeholder Collaboration Strategy with Rational Requirements Composer: Part 2. Organizing the project and repository space

This is the second in a series of four articles about configuring and using IBM® Rational® Requirements Composer. The series covers four key areas: audience, organizing the project and repository space, linking strategy, and collaboration strategy. This reflects the need to determine the audience, decide which artifacts will help agree and validate requirements, and the need to plan a collaboration strategy with the audience. The last section sets out a plan for reviewing and improving the process for the next time.

Lisa Garrity (garrity@uk.ibm.com), IT Specialist, IBM

Author1 photoLisa Garrity works as a technical consultant for IBM Rational software in the UK. She has worked in the software development field for 16 years in consulting and technical sales roles. Her primary responsibilities have included eliciting, managing, and documenting requirements for business and systems analysis, as well as supporting customers in their quests for success in software development. Lisa is a Rational Requirements Definition and Management Regional Mentor in the UK and joined Rational software in 2002.



Paula White (paula.white@uk.ibm.com), Consulting IT Specialist, IBM

Photo of Paula WhitePaula White is a technical consultant for IBM Rational software in the UK. She has been working in the software development field for more than 19 years. She has worked as an architect, software engineer, trainer, coach, mentor, and consultant. Currently, she works as a Rational brand architect and leads the UK Rational Brand Architects team. She is a Requirements Definition and Management Regional Mentor in the UK. She joined Rational software in 2002.



31 August 2010

Also available in Chinese Spanish

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
Organization overview diagram

Folder structure

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)
  • Storyboards
  • Glossary
  • Pre-project documentation
  • Workshop notes
  • Checkpoints
  • 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
  • Epics
  • User Stories
  • Glossary
  • Storyboards
  • 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
Functional areaInformation
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.

Tags

Tagging tips

Tags are most effective when applied consistently.If adopting a policy of using specific tags (for a business area, for example), communicating the benefits of the approach and educating authors is vital to success.It is also advisable to assign someone from the project team to take responsibility for ensuring that tags are assigned to a particular area.

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.


Attribute groups

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.

Attribute tips

A requirement type is determined by the associated attribute group.Attribute values need to be maintained to be helpful. Keep the number of defined attributes to an absolute minimum.

Requirement types

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 groupAttributeAttribute values
Storyboard attribute group State In progress (default)
Reviewed
Under revision
Validated
Approved
Test ranking Testable
Under revision
Not testable
Architectural review Reviewed
Under revision
Complexity to implement Complex
Average
Low
Originator Paula
Lisa
Vivianne
Robin
Contact person Kirk
Daniel
Judith
Claire
Table 3. Example of a table to show an attribute group definition
Attribute groups Feature Use case Supplemental Storyboard Origin
Artifact types
Actor X
Collection X
Glossary X
User interface part X X
Business process diagram X
Requirement X X X X
Document X
Screen flow X X
User interface Sketch X
Storyboard X X
Term X
Use case X
Use case diagram X
Resource wrapper* X

*Resource wrapper is for all external artifacts that have been loaded into the repository, such as JPG files of whiteboard sessions.


Filters

Tips:
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.

Shared filters

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.


Collections

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.


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.


Summary

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 organizationDescription
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.


Acknowledgements

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.


Download

DescriptionNameSize
Stakeholder_Collaboration_Strategy_template.docStakeholder_Collaboration_Strategy_template.zip105 KB

Resources

Learn

Get products and technologies

Discuss

  • 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.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=513228
ArticleTitle=Using the Stakeholder Collaboration Strategy with Rational Requirements Composer: Part 2. Organizing the project and repository space
publish-date=08312010