Gatherspace Reference Manual
& Quick Start Guide (v2.20)
Gatherspace is a powerful hosted requirements management and use case tool for managing and sharing software requirements. It frees you to focus on your requirements without concern for upgrades, infrastructure, and maintenance.
This reference manual is intended to give you assistance in the fundamentals of setting up and using your Gatherspace. Everything that you need to know to be productive with the system will be in this document. For futher assistance you may email firstname.lastname@example.org.
Table of Contents
Whether you begin with a free trial or a paid account, your opening screen will appear as shown below.
This screen is the Home Page for your Gatherspace. You can use the top level tabs to navigate to different system sections such as Requirements, Projects, Reporting, etc.
On the initial screen, you are defaulted into the ‘Requirements’ tab where you can start adding your Business Requirements.
1 Start by setting up at least one user for your Gatherspace. Click the All Projects on the upper left navigation.
2 Click Manage Users.
Referencing the upper screen, you can click on the Users link to add and manage new users.
3 Click the email address which appears.
If you are using the free trial, you are limited to one user, employing the email address and password you used when you signed up. The role of this user should remain as Administrator so that you will be able to make any necessary account changes.
4 Enter the full name for the displayed email address and password user.
5 Check the ‘Send email notifications’ box to have emails sent to the email address shown.
6 Click Update to accept the information shown.
7 If you have a paid account, you may set up additional users by entering a new email in the ‘Add User Email’ box and clicking Add User Email. Enter other information about the user as described above. These users may be assigned roles as Read Only or Read/Write, as well as Administrator.
It is wise to carefully think through what role you assign to each user. Administrator privileges should be assigned only to those who will need to make basic changes to your Gatherspace. Read/Write roles should be assigned to all who will be making changes to your requirements. Others should be assigned Read Only roles.
1 To give your first project a name, click All Projects on the upper left nav and click the New Project button to add a new project.
2 Select a project in the project list and click the Edit Project link.
3 Change the ‘My Project’ name to the project name of your choice.
4 Enter a brief description of your project in the Project Description box.
You can come back and change any information on this screen at a later time, so if you are not sure what you want to enter, just leave the box blank.
5 Leave the Default selection set at “Yes.” When you have multiple projects, you can set the default to “Yes” for the project that you want your Gatherspace to automatically open to.
6 The Business
7 Click the pull-down arrow beside ‘Project Owner’ and select the owner you want to assign this owner to.
8 Click Update when your entries are complete.
If you are using the free trial, you are limited to one project.
Think of a Package as the top most conceptual level of the requirements hierarchy of the pyramid. A package is a grouping of business requirements which in turn have requirements and use cases associated with them.
Using the example of trying to build a consumer based shopping cart, a package would be “Shopping Cart”. A business requirement of the package “shopping cart” would be “..the system will allow the consumer to empty the shopping cart.” Requirements which fall under that would be anything at the implementation or specification level that has more granular detail.
Business Requirements are the beginning point in constructing your project specifications. A Business Requirement is a simple description of something the system will do to solve the problem at hand. It should describe the “what?” as opposed to the “how?” and not describe any implementation detail.
After some business requirements have been defined, software requirements can be added. A software requirement is a description of how a business requirement is carried out. For example, a business requirement of an online bookstore might be to provide shopping cart functionality. Some software requirements for that shopping cart might be to allow items to be placed in the cart, items to be removed from the cart and for the cart to be cleared of all items. It is important to understand the difference between a business requirement and a requirement before beginning to add business requirements. Business requirements are the top level of project definition. Requirements support or supplement business requirements.
If you find that your business requirement is long and detailed, chances are it should be considered a requirement and not a business requirement.
1 Click the Requirements tab
2 Enter the name of your business requirement in the box beside ‘Add Record.’ A description of the business requirement will be added later.
3 Click Add Record.
4 Repeat steps 2 and 3 above for other business requirements you want to add.
5 After business requirements have been added, descriptions for each business requirement may be added, along with other details regarding the business requirement. Click the Key or Name for any business requirement to open the Detail screens.
The screen you seel below is the ‘BR Detail’ screen which first allows you to view the record and do other things before editing. This includes:
1) Add attachments.
2) Copy the business requirement
3) Printable View
4) Associate and add new software requirements
5) Associate and add new use cases
6 Once you click the ‘Edit Record’ button you will get taken to the detail screen in the image below. Enter a description of the business requirement in the box provided. Text formatting controls are provided below the box so you can add bolding, special font colors, etc.
Assign the appropriate Priority and Complexity for this business requirement.
Assign the proper Status. Generally, when a business requirement is first established, it would be assigned a ‘Submitted’ status, but you can apply one of the other status levels according to the process your organization will use.
You may indicate ‘Assigned To:’ and ‘Requested By:’ individuals as appropriate.
If this business requirement is associated with more than one project (see Project Mapping below), you may indicate the primary project this business requirement is associated with.
Click Update when complete.
8 Business requirement Views – whenever business requirements for a project are displayed (by clicking Business requirements in the Project Specifications list), a choice of views is available. The Current View is shown in the pull-down selection box at the top of the screen, as shown below.
Requirements, as noted under ‘Add Business requirements,’ exist to support or supplement business requirements. A requirement is a description of how a business requirement is carried out. After business requirements have been created, requirements can be added to support them.
1 Click Requirements in your Project Specifications list.
2 Enter your first requirement in the box and click Add Record.
3 Enter additional requirements as described above.
4 All requirements must be mapped to a business requirement. To perform this step, click the Key or Name for any requirement.
5 Enter a description of the requirement in the box provided. A description should be of the form of “The system shall…” to properly describe the requirement. Text formatting controls are provided below the box so you can add bolding, special font colors, etc.
Associate this requirement to a business requirement by clicking the pull-down arrow beside ‘Associated Business requirement:’ and selecting the business requirement.
If use cases have been created, you may also associate this requirement to a use case by clicking the pull-down arrow beside ‘Associated Use Case:’ and selecting the use case.
Assign the appropriate Priority and Complexity for this business requirement.
Assign the proper Status. Generally, when a requirement is first established, it would be assigned a ‘Submitted’ status, but you can apply one of the other status levels according to the process your organization will use.
You may indicate this requirement is ‘Assigned To:’ an individual as appropriate.
You may also enter a version designation to identify this requirement.
Click Update when complete.
Actors are not specific people (such as Bill or Jan), but are roles which may be fulfilled by people or other entities interacting with (using) your system. Actors fulfill their roles to achieve desired goals. For example, if there is an actor called "Customer Service Agent", the actor goals could be, (1) Answer customer service calls, (2) Submit customer service tickets into system, (3) Monitor customer service queue. Note that the system itself is not entered as an actor.
1 Click Actors in your Project Specifications list.
2 Enter your first actor in the box and click Add Record. Remember, the actor designation is not a person but a role, such as buyer or seller.
3 Enter additional actors as indicated above.
5 Enter a description for the selected actor. Text formatting controls are provided below the box so you can add bolding, special font colors, etc.
The Person Type may be selected by clicking the pull-down arrow. In addition to Actor, you may choose Stakeholder or System. A Stakeholder is someone who has an interest in (and is affected by) the project system but is not an actual user (actor). The System choice represents some system separate from your project system but which interacts with your system in its normal operation.
Click Update Actor when these selections are complete.
When an actor (user) interacts with your system to achieve a goal, a use case is established. A use case can be thought of as simply one of the ways your system is used – a case of use, like an online bookstore customer placing a book in the shopping cart. Since there can be many actors pursuing several goals, there are usually many use cases associated with any system project. By accumulating all the use cases, the function of your system is fully described. As we will see later, these use cases are automatically made available in graphic form as well.
1 Click Use Cases in your Project Specifications list.
2 Enter the first use case in the box and click Add Record. Since a use case is an example of what a user does when interacting with your system, it should be stated in the form of an action, like ‘Put books in shopping cart.’
Each use case must be associated with an actor (user). But this will be done later, so in this step, just enter the use case itself.
3 Enter additional use cases as indicated above.
4 Enter details of a use case such as actor assignment by clicking any use case or its ID number.
5 Enter a description for this use case.
Assign a primary actor by clicking the pull-down arrow and selecting an actor.
Enter a precondition, if appropriate. A precondition is some other action that must take place before this use case can happen.
Assign the appropriate Status and Priority for this use case.
Associate a business requirement with this use case if appropriate, by clicking the pull-down arrow and selecting the business requirement.
Click Update when the entries are complete.
6 Basic Flows – for each use case (each interaction of a user with the system) there may be several system responses. The responses that would normally occur are called Basic Flows. For example, for the use case of a bank customer getting an account balance from an ATM machine, some normal flows might be to ‘select to view the account balance’ or ‘select to end the transaction.’ (Some unusual responses called Alternate Flows may also occur and are described later. Both need to be entered to fully describe the system.)
A basic flow for any use case can be entered in the box at the bottom of the use case detail screen, shown above in step 4. Enter the basic flow and click Add Basic Flow Event. Additional flows can be added in the same way. As they are entered, each flow is automatically assigned an ID number.
7 The Basic Flow you have entered defines the user input, but to complete the flow it is also necessary to record how the system responds. To add this response information, click on the ID or Name for any basic flow.
Enter the system response and click Update Flow Detail.
8 Repeat for each basic flow until all basic flows for this use case have been described.
Flow list organization – when several basic flows have been entered, you may want to organize the list in some particular order for ease of use. To do so, using the sequence/rank field, submit a number into this field and the flows will align in the reports appropriately.
9 Alternate Flows – a complete system response to a user’s inputs must include unusual events. For the ATM example and the ‘System provides receipt’ use case, the system could run out of ink and be unable to provide a receipt. Such unusual events are called Alternate Flows and must be entered along with the corresponding system response. To enter an alternate flow for any use case, open the use case by clicking its ID or name.
10 Click Alternate Flows which appears at the top of the use case detail screen (red arrow above).
11 Enter the alternate flow in the box and click Add Alternate Flow. Enter additional alternate flows for this use case as necessary to fully describe it.
12 When you enter an alternate flow, it is automatically assigned as an alternate use case and appears indented in the list of use cases below the main use case it is associated with. For example, see the alternate use case ‘Alt UC4945,’ shown below.
13 An alternate use case, like main use cases, should be described, an actor assigned, etc. To do this, click the alternate use case ID or name.
14 Enter the description, assign the actor and complete the other fields as was done for a main use case. Click Update when complete.
15 When an alternate use case has been defined, its basic flows should be entered. From the use case list click the alternate use case to display the Alternate Flow Detail screen (as shown in step 13 above). Enter the basic flow in the box at the bottom, then click Add Basic Flow Event.
It may seem strange for an alternate use case to have basic flow events, since we made a distinction between a basic flow and alternate flow. But any use case, main or alternate, has a normal set of user actions and system responses which become the basic flows for that use case.
16 Often basic flows involve one or more system responses without corresponding user actions. In that case, enter the system response as the basic flow event, then on the flow detail screen, move the system response to its correct box and place a dash (-) in the user action box. An example is shown below.
Basic Flows and Alternate Flows are managed the same way. The only difference is that the alternate flow is first named based on an existing use case.
A project glossary allows you to define and explain terms which are used in the project requirements. This can be particularly helpful when unique terminology or business slang is used in describing this project. The glossary list will appear at the bottom of the completed Project Vision & Requirements document.
1 Click Glossary on the Project Details list.
2 Enter a glossary term in the box and click Add Term.
3 Click the Key or Name for the term.
4 Enter the description of the glossary term.
5 Click Update Term.
6 Enter additional glossary terms and descriptions as necessary.
As you use your Gatherspace, you may encounter problems with some screens functioning properly, or have some suggestion for improving the way the application performs. The issues manager allows you to enter and display all such items.
1 Click Issues on the Project Details list.
2 Enter the issue in the box and click Add Issue.
3 To add details, click the ID or Name of the issue.
4 Enter a description of the issue in the box provided.
Make appropriate selections for Priority, Complexity and Status.
Click Update when all selections are complete.
5 Enter additional issues in the same manner.
The Reports section is found beneath your Project Specifications list and provides the means to look at the complete project from several viewpoints.
1 Product Requirements Document (PRD) – click to display the complete project in outline form, preceded by the main outline points (shown below). Project business requirements are shown in the requirements section.
Click Print Window to open the document full-screen in a new window for printing purposes.
Click View as PDF to open the document as a PDF in a new window. You may save a copy or print the document.
2 Use Case Specifications – click to open a screen which allows selection of the criteria used the filter the report of use cases.
Select the desired criteria or just click Run Report to see all use cases.
3 Business requirement Report – click to open a screen which allows selection of the criteria used the filter the report of business requirements.
Select the desired criteria or just click Run Report to see all business requirements.
4 Requirements Report – click to open a screen which allows selection of the criteria used the filter the report of requirements.
Select the desired criteria or just click Run Report to see all requirements.
5 Use Case Model – click to display a graphical representation of established use cases.
Click New Window (red arrow) to view the use case model in a new browser window.
6 Traceability Report – click to display a report which shows the bi-directional linkage between business requirements and uses cases and between business requirements and requirements.
7 Issues/Bug Tracking Report – click to open a screen which allows selection of the criteria used the filter the report of issues and their status.
Select the desired criteria or just click Run Report to see all issues.