Borland StarTeam: Agile Requirements
Agile requirements
eXtreme Programming, Scrum and Feature-Driven Development express the requirements for a piece of software as user stories, backlog items, and features respectively. While the details differ, all three types of agile requirement start as little more than a name for a requirement and are elaborated as development proceeds.
Agile requirements also play a dual role. They are not only used to define what the software should do, they are also used to plan and track the progress of the development of the software through a series of iterations.
Although excellent at what they are designed to do, more traditional requirements management tools like Borland CaliberRM were not designed with this dual role of agile requirements in mind. In contrast, Borland StarTeam (Enterprise Advantage) provides a single integrated repository for version controlled source code, requirements, change requests, topics, and tasks. Therefore, StarTeam’s integrated approach frequently provides a better platform for managing agile requirements than a traditional requirement management tool.
User Stories
eXtreme Programming and an increasing number of Scrum projects use user stories to record requirements, and plan and track project progress.
Traditionally written on index cards, a user story starts as a short statement written by the customer describing something that they want the software to do. It is a ‘chunk of functionality that is of value to the customer’ [Beck, Fowler 2001] and starts life as ‘…nothing more than an agreement that the customer and developers will talk together about a feature.’ [Beck, Fowler 2001]
The customer is expected to prioritize their user stories in terms of value to the business. This is generally done by sorting the user stories into an ordered list with the more important ones at the top.
The development team estimates the effort required to implement a user story by assigning each user story a multiple of some unit of effort. Traditionally, in eXtreme Programming and Scrum, this unit of effort is an ideal day where an ideal day is defined as the amount that can be achieved by a developer in a day without any distractions. This leads to difficulties as different developers can achieve different amounts in an ideal day. More recently the more abstract ‘user story point’ has become popular because it
properly disconnects the relative size of a user story from any form of elapsed time or individual performance (see [Cohn]).
Development is organized into a number of very short, fixed duration iterations typically of two weeks for eXtreme Programming and one month (30 consecutive calendar days [schwaber]) sprints for Scrum . Iterations are then typically grouped into releases. Release cycle length varies from team to team but is typically three to six months.
At the start of each iteration the development team commits to deliver a certain set of user stories. The team uses the number of ideal days/user story points delivered in previous iterations to predict how many ideal days/user story points they will deliver in this iteration. This is the team’s estimated capacity for this iteration. The team then picks a set of user stories based on business value and technical risk whose total estimated size fits within the iteration’s estimated capacity.
Once the initial set of users stories has been selected, each user story is also broken down into a number of technical tasks that need to be completed to deliver the user story. Developers sign up for the tasks they can complete during the iteration, estimating how long it will take them to complete each one. If necessary, the original set of user stories is adjusted based on the more detailed estimates.
At the end of each iteration, the development team reviews the delivered (coded, tested and documented to agreed project standards) user stories with the customer.
At any point, a customer may adjust the business value of any of the outstanding user stories, may add new user stories, and remove any outstanding user stories that are no longer needed. However, with very few exceptions, the development team does not take into account any of these changes until the end of the current iteration.
StarTeam and User Stories
When the team is collocated, index cards are one of the best tools for recording and working with user stories and related tasks. They help keep planning and estimating sessions dynamic, and the cards can also be pinned on an accessible wall so that they can be updated easily each day to track status and progress.
Where index cards become problematic is where teams are distributed, even when that distribution may only be across separate floors or wings of a building. The amount of time a developer spends walking to and fro between the project wall and his workstation becomes significant. Reporting status to senior management across a significant number of agile projects is also more difficult when user stories and tasks are only written on index cards.
The usual reaction to these issues is to enter the user stories into a spreadsheet and put that somewhere accessible to all team members. The best location is usually in the same version control system (vcs) that the project is using to store its source code and other project artifacts. An alternative is a shared folder on a network drive but the same reasons why source code files are better off in a purpose-built version control system apply.
The spreadsheet approach has the usual drawbacks of all single-user, general productivity tools:
-
only one person can edit it at a time,
-
it is hard to see which user stories and tasks have changed in a new version of the spreadsheet
-
unlike an index card where scribbled amendments over time are obvious, it is difficult to examine the history of an individual user story or task.
-
it is hard to roll up information from several projects into an overview for senior management
We could store each user story as a separate file in the vcs. However, this raises questions like:
-
the best format for storing and viewing, plain text, HTML, XML, etc.?
-
do we store tasks as separate files or put them in the same file as the user story?
-
how do we compile summary information like total estimated time left to complete all the tasks in an iteration compared to the time left to the end of the iteration?
An alternative to the spreadsheet approach, assuming the project has one, is entering the user stories and tasks in pages on a wiki site. This is worth considering but suffers from many of the same drawback as the spreadsheet approach and raises additional questions like:
-
how do we easily associate the user stories completed in a release with the source code and other project artifacts that form the finished release?
-
do we put each user story on a separate page and link to it from page listing all the user stories in a release, and again from another page listing all the user stories in an iteration? If so what information do we duplicate on the list pages and how do we ensure the duplicated information is consistent?
-
how do we compile summary information like total estimated time left to complete all the tasks in an iteration compared to the time left to the end of the iteration?
StarTeam provides another alternative. It includes relatively light-weight (when compared to dedicated requirements management and project management tools) requirement and task modules. These modules enable requirements and tasks to:
-
be stored along with all the other artifacts of a project
-
version controlled individually
-
accessed concurrently
-
be associated with each other via StarTeam’s linking features
-
labeled with the source code and other project artifacts that form a finished release of the software
-
viewed as lists filtered by user definable queries.
-
viewed individually in purpose-built forms.
Conceptually, therefore, it is a relatively easy to see that if we need to store user stories and tasks electronically then StarTeam requirements and tasks would make a good option.
Selecting one of the requirements causes details to be displayed in the bottom panel. Figure 1 shows the history of the selected requirement. Other tabs show links to other items such as related tasks, any labels showing which releases a requirement is part of for example, etc. The tasks module is similar.
Figure 1 shows the StarTeam cross platform client listing a set of requirements. The list can be displayed in a different order by clicking on the appropriate column heading.
Figure 1: The StarTeam
Standalone Client - click for larger image
Double-clicking on one of the requirements in the list in Figure 1 causes the requirement to be displayed in detail in a purpose-built property editor window. Figure 2 shows an example.
Figure 2: The Standard StarTeam Requirement Editor Dialog
Business Value, Technical Risk, Priority and Size
By default, requirements in StarTeam have a priority field and a number of fields for estimating the effort required to meet the requirement.
The priority field takes one of set number of values. By default these values are Unassigned, Essential, Useful, and Desirable but this can be changed by a user with appropriate access permissions.
This approach to prioritization is a good starting point but for user stories we really need a finer grain approach that enables the stories to be ranked in order of importance. Instead of one of fixed set of values we want a priority field that takes a numeric value so that we can sort on it. StarTeam does not allow the priority field to be changed to take a numeric value but it does allow the definition of additional fields.
Therefore, we can define a new numeric field, called rank for example, and this will appear on the custom tab of the requirement dialog shown in Figure 2. We can even define a default value for the field. For example, using 9,999 as the default should mean that new user stories appear at the bottom of any list that is ordered by rank until their relative importance has been decided.
We also have another choice to make. We can specify the field as holding integer values or real (floating point) values. Specifying real means we can always insert a user story between two others in terms of rank. For example, if we have two user stories with ranks of 1.5 and 1.6 respectively, we can insert a new user story between them by specifying a rank of 1.55.
As stated earlier, the rank of a user story is determined by looking at business value and technical risk. Generally, teams want to develop the user stories that represent the most business value and the highest technical risk first. The business value is determined by the customer and the technical risk by the development team. While we can capture these as part of the description in a StarTeam requirement, defining additional fields for these two values enables user stories to be very quickly re-ordered by either of these values. This makes these values available in reporting and scripting contexts too.
The other important thing we need to do is store the estimated size of a user story. We could reuse the Estimated Effort field for this. However, where an organization is also using StarTeam requirements in a more traditional way, it avoids confusion if a separate custom field is defined to hold the size of the user story in terms of ideal days or user story points.
Figure 3 shows what the custom tab in the StarTeam requirement property editor looks like with rank, business value, technical risk and size fields defined.
Figure 3: Custom Fields asses to a StarTeam Requirement
Figure 4 shows a list of requirements in StarTeam that displays the custom user story fields and sorts the user stories by rank. This is achieved using another of StarTeam’s standard features, filters. A new filter, called User Stories, is easily created to display the appropriate fields and sort the list by rank. A filter is applied by selecting it from the drop down list on the main toolbar.
All users can define new filters for their own personal use so different people can display user story information in the way they find most useful for a particular activity. Users with appropriate permissions can also define filters that can be used by all users (public filters). Therefore, a set of useful filters for viewing user stories can be created and made generally available.
Figure 4: StarTeam
Requirements - click for larger image
As user stories are elaborated, notes and related reference documents can be attached using the attachments tab in the StarTeam requirement property editor. These attachments are then available for all users to easily reference at any time, something that is harder to achieve with index cards.
Comments can be added for each change made to the User Story if it is helpful to do so using the Comment tab of the requirement property editor, and team members can sign up for a user story (although this is more usually applicable to tasks) using the Responsibilities tab. When working with user stories, the other tabs and fields in the requirement property editor are only used if they are genuinely useful in a particular circumstance.
While using simple conventions like those described above is often good enough for many situations, StarTeam also allows the requirement property editor to be replaced by a custom-built alternative developed in Java. This can be useful where an organization wants to hide unused fields, add more specific functionality, etc.
StarTeam supports the definition of multiple APE’s enabling a project to pick the one that best matches their needs.
Another general benefit of using APE’s is that they enable custom workflows defined with StarTeam’s workflow designer to be used. Few agile development teams, however, require anything more in terms of workflow than a simple status field that takes one of a handful of set status values. In many cases, the built-in status field of a requirement is good enough but, again, a custom field can be defined to replace it where it is not.
The discussion above has focused on user stories but the same principles apply equally to StarTeam’s task module. Just like requirements, StarTeam tasks can
-
have additional custom fields defined for them
-
have filters defined to display the appropriate fields in lists
-
be listed in different orders
-
have alternative property editors defined for them