Working with Work Items: Managing change using best practices
This article provides an introduction to how work items are used to collaborate across the development lifecycle and discusses best practices teams can use to be more efficient when creating and handling work items and process configurations.Working with Work Items
Work items organize the information used to manage change, enable people to collaborate, link work products together, simplify planning, enforce process constraints and help optimize productivity for both agile and traditional software development teams. The type of work item determines what attributes are managed by the work item as well as how the work item is used in the team’s process. The process configuration for the type defines how the attributes are presented as fields, selection lists, and other widgets in the various work item user interfaces. Types include Stories, Tasks, Enhancements and Defects, plus many other types used in the various process templates or customized using the process editors.Work Items manage change in many ways. For example when new features are added to a product, a Story will be created to describe how things should work.
Figure 1. Defining a Story
The story also defines what constitutes the “Acceptance Criteria” (a.k.a., “Done Criteria”) to consider the story complete.
Figure 2. The acceptance test describes the done criteria
From the Story, additional work items are extracted so the work that needs to be performed to realize the story is represented by a set of Enhancements that must be implemented, Tasks that must be performed, and Defects that must be fixed. The work described in the work items is performed by product developers and other contributors to the product. When the work items extracted from the story are complete, the story is realized.
Figure 3. A story can have child work items which implement the story
Product development is done by performing the work described in the work items. Each work item goes through a series of state transitions as it moves through the process; for example, a work item can start out “New”, then become “In Progress”, then “Resolved”, then “Verified”, and finally “Closed”. When a work item is resolved — or closed, depending on your process — the work is complete. The work item describes the problem or task and the context of the work, while discussions capture the collaboration among stakeholders and contributors. In the discussion, when one work item mentions another work item, both “mentions” and “mentioned by” links are automatically generated to link the two work items together. In addition, a comment can call out a specific user, which will notify the user about the comment; for example, via a feed event or e-mail, depending on how the user configures notifications.
Figure 4. Mentioning a work item automatically generates a link to that work item. The @user references inform other users that a comment has been directed at them.
Work Items can be searched and organized using queries. A query is defined by creating a set of conditions.
Figure 5. Queries are used to organize and search work items.
For software development, file changes are managed as change sets which are associated with work items. The history of a source file shows what work items and users were involved with changing the file.
Figure 6. In Eclipse, source files can be annotated to map lines of code to the history of change sets delivered via work items.
Coordination of file changes with Rational Team Concert Software Configuration Management (SCM) is done by delivering changes into a shared stream. A Pending Change view in Eclipse shows:
- changes made by the current developer that are outgoing into the stream,
- contributions from other developers that must be merged into the current developer’s workspace or sandbox that are incoming from the stream,
- suspended changes, as well as
- unresolved changes and patchs.
For software products, source code changes are managed such that they are delivered via change sets which are associated with work items. After all the change sets associated with a work item are delivered to the stream and the work is complete, the work item state is set to “Resolved” or “Done”. Work item state changes are made using state change actions such as “Resolve”, “Close” or “Reopen”.
Builds are performed by compiling change sets from a stream. Since work items are linked to the change sets used to perform the build, the work items are linked to the builds as well. Thus, it is easy to see what builds included the changes for a work item, and to see what work items contributed to a certain build.
Figure 7. Software source file changes are managed by change sets which are associated with work items.
Similarly, the changes in a particular build of a product can be traced back to the work items, contributors, and change sets that produced the build.
Figure 8. Software changes are integrated and compiled using builds which are linked to work items.
Work items that will not be fixed can be resolved as invalid, found to be working as designed, or marked as something that won’t be fixed. Duplicate work items are merged such that the severity and subscribers of the second work item are added to the first work item, then the second work item is resolved as a duplicate of the first. When creating work items it is important to avoid creating duplicate items by using the “Find Potential Duplicates” action from the work item editor. Use the action after filling out the work item but before saving. The “Find Potential Duplicates” action runs a query which is constructed by using the content of the work item to create conditions to search for similar work items.
Figure 9. Potential Duplicates search uses a work items content to search for similar work items.
Completing work items with appropriate resolutions is important because it keeps the plans, dashboards, reports and quality audit data more accurate. Many kinds of reports are available to help understand productivity and quality trends based on work item content and state.
Figure 10. Reports display work item analytics.
When using an agile process, work is planned by establishing a set of milestones such that at the milestone end-date a set of work items has been resolved and a stable version the product is available for usage, testing and derivative development. When the planned for milestone is assigned to a work item, the work item appears in the plan for that milestone; similarly, when a work item is added to a milestone plan the planned for milestone attribute is assigned in the work item.
Figure 11. Plans are constructed by assigning work items to iterations and owners.
The status of a project can be displayed in highly customizable dashboards. Dashboard viewlets provide a concise glimpse into an aspect of the project.
Figure 12. Dashboards provide a snapshot into project and team status.
Ideally, all the work performed is tracked with work items. After the product build is available at the end of each milestone, a subset of the work items resolved are verified to confirm that they have been resolved properly. Verification is tracked using work item approval records and status changes.
Where different product components interact, such as when one software component promotes a change that must be adopted by another component, work items are used to propose and track adoptions of the interdependent changes. Where different products interact, work item linking between their respective project areas allows work tracking to flow from one product to the other. Testing, fixing, polish, and real-world usage of the product in a controlled environment is performed over additional milestones to hone the product until it is ready for release, as determined by work item approvals that must be approved by contributors and stakeholders. The IBM Rational Collaboration Lifecycle Management products — including Requirements Manager, Team Concert Change and Configuration Manager, and Quality Manager — are “self hosted” using jazz.net such that the products themselves are used by the product managers, product developers, testers and other contributors and stakeholders collaborating to create the products. Self-hosting has refined these products through hands-on use so they provide a high quality and efficient user experience.
The flow of work items through the team is controlled by a process. The process determines the state transitions for the work items and adds requirements on the work item content and their related artifacts; for example, a process may be configured such that during end-game milestones just prior to product release — when risk must be balanced against the impact of not fixing a problem — both a team lead approval and a code review approval are necessary before a software change set can be delivered into the production stream.
Figure 13. Approvals can be used to control state changes and code deliveries.
Work items link to related artifacts, including screen captures, file attachments, software change sets and other resources such as web sites, plans, software builds, requirements, and test cases. Work items can also link to other work items both in the local repository and in associated project areas in the “friend server” network. For complex work items it can be necessary to refine the task by extracting additional work items; these can be organized as independent work items, related work items, or in a parent-child relationships with other work items.
By linking together many different kinds of artifacts work items help to manage the project across the collaborative lifecycle.
Figure 14. Work items can be linked in various ways to other work items and various artifacts.
Work items can be linked to test cases to track their verification.
Figure 15. Within Quality Manager, test cases can be linked back to the work items that they test.
Once a product is released “into the wild”, consumers not associated with product development use the product. As more people use the product they find additional Enhancements, Defects and Tasks. These are either solved directly or are used to create stories. In an open product development process, product consumers can collaborate directly with product developers and other contributors by creating work items and participating in their resolution. In a more traditional support structure, change requests from the customer (e.g., APARs) are shadowed as work items which flow through to development teams from the customers via the support teams.
Work items can track the implementation of requirements, so consumers can work with product managers to define requirements which are then implemented using work items.
Figure 16. Within Requirements Manager, work items are linked to requirements.
When a work item is referenced from a collaborative lifecycle management application — such as change management, quality management, and requirements management — hovering the mouse over the link will show a compact rendering of the work item. Similarly, the compact reference to artifacts referenced from work items can usually be seen by hovering over the link. To edit the work item or resource, the work item link is clicked.
Figure 17. Hovering over a link to a work item will show the compact rendering. Clicking the link or work item number will open the work item in an editor.
When work items are created or modified, the team is notified via dashboards, feeds, queries and e-mail subscription notifications.
Figure 18. In Eclipse, the Team Dashboard displays feeds showing work item activities.
The team — often the team lead — performs triage on each incoming work item to refine the category it was filed against, determine the priority, assign an owner, and plan for its resolution. New work items are either planned for a milestone or assigned to the backlog, to be resolved in a different planning cycle. The backlog is a list of work items waiting to be resolved while the work items planned for the upcoming milestones are being worked on. As the product evolves, work items are removed from the backlog by being assigned to a milestone for resolution. Meanwhile a stream of new work items flow through the team.
Each work item in the plan has an owner who is responsible for it’s resolution. New work items appear in the owner’s My Work Inbox, available in the Eclipse workbench. From the My Work view, the work item owner can performs additional triage to verify the planned for milestone, assign a priority, estimate the time it will take to complete, search, filter and otherwise organize their current work assignments.
Figure 19. In Eclipse, the My Work view can be used to manage a contributors day-to-day tasks. Other views integrate work items into development tasks.
Work items in the current milestone should be resolved in priority order, and can be individually organized in ranked order. Since work items can be generated from all past releases of a product, owner triage also includes verifying or determining what environment the problem or enhancement request was found in, ensuring that the problem can be reproduced, and checking to see if the work item is a duplicate of another existing work item.
Occasionally an owner will determine that the work item needs to be reassigned to a different owner, should be filed against a different component category, or moved to a different project area. These changes can be made by opening the work item editor and changing the work items attributes. When the work described by the work item is complete, the work item status is changed to show that it is done or resolved.
To enable maximum flexibility in the way teams can manage change following their own process, administrators can customize work items to:
- Add new work item types, attributes and enumeration values
- Change the presentation of attributes within a type
- Define states, resolutions, and work flows that regulate state transitions
- Define team areas, project members, roles and permissions
- Provide scripting, define attribute dependencies, and mark required attributes
- Add new services and presentation components
Figure 20. In the Project Administration pages, types and attributes can be customized.
Each work item type can define it’s own presentation of the work item attributes.
Figure 21. In the Project Administration pages, the presentation of attributes can be customized.
The process work flow defines the work item states and the actions that cause state transitions.
Figure 22. In the Project Administration pages, the process workflow can be customized.
More complex customizations can be made extending the product by adding user interface presentations and REST services. For example, an extension allows work items interactions to contribute to collaborations within Lotus Connections social networks such as the IBM MyDeveloperworks site.
In a typical team, each contributor can be managing hundreds of work items at any particular time. Thus it is important to strive to create work items that are easily manageable without adding excess overhead for the people using the work items you create and interact with. Using best practices when creating and managing work items can help maintain the efficiency of the entire team.
Using Best Practices
Every team has its own style of using work items. The process configuration for each project area also changes the way work items are used, and each type of work item can be used differently. However, after years of self-hosting, several best practices can be identified to optimize communication and minimize friction when working with work items.1) Write good summaries. The summary is the most important element of the work item. In general, the summary is a single sentence, but there is no period at the end. Work item summaries appears in countless places throughout the product, including in work item links, query results, dashboards, plans, build results, pending changes, search results, in the My Work view, in requirements links, and test case links. Thus it is imperative that the summary be concise and informative, without assuming that the reader knows the context or is viewing the full content of the work item. With a good summary, many work item management tasks such as assigning priority and ownership can be performed without having to open the full editor on the work item. The summary should be concise, informative and free from grammar and spelling errors.
For example “Long project area names are clipped in the work item editor” is a better summary than “Layout problem” because the former describes what the problem is and where it occurs.
Figure 23. Writing good summaries makes it easier to manage work items. Here, Work Item 82110 does not have a good summary.
2) Be descriptive, but concise. Work item descriptions should be thorough and to-the-point. Fill out all relevant fields, even if they are not required, especially Severity, Found In, and Client (e.g., web or Eclipse). For software, when Found In is not concise enough for the developer to know what level of code the problem occurred in, paste the current “About” information in the description to show the particular build where the failure occurred. On the other hand, do not assign an owner, priority, or planned for value to work items unless you are the team lead or work item owner. Attach good screen shots. A screen shot is often the easiest way to describe a problem. However, if the screen shot is a small portion of the screen, sometimes it can be difficult to get the full context of the problem. So usually it is best to include the full page or view when snapping screen shots, then use the outline shape tools to highlight the problem area. Since screen shots attached as .png or .jpg files can be viewed by hovering over the link, avoid attaching PDF or Word documents with embedded screen shot that must be opened externally. Also avoid .bmp format screen shots as these are unnecessarily large and do not show in the preview.
When an approval is requested, add a comment to indicate what the risk and impact of the change would be.
Figure 24. When creating approvals, describe the status, risk and impact of the change so the person approving can know the context.
When appropriate to debug the problem, attach any relevant logs, and copy the important part of the log to the description.
For defects, the description should include the context and steps to recreate the problem.
Figure 25. A good defect description makes it easy to recreate the problem in the environment where it occurred.
For enhancements, describe the context, then request the enhancement by completing the sentences: “It would be nice if…”.
Figure 26. A good enhancement description makes it easy to understand what is desired and why it is important.
3) Search for Potential Duplicates. Identifying and resolving duplicate defects and enhancements is one of the most expensive ways development teams waste time during a development cycle. When creating work items, fill in the “Filed Against”, tags, description and summary then use the “Find Potential Duplicates” action to run a query to see if any obvious duplicates exist. Although sometimes a duplicate exists which can’t be found, often a duplicate will show up as the first item in the list, especially if the summaries of both items are well written. If you find a duplicate, add yourself as a subscriber to the other work item and, when appropriate, add a comment indicating how you experienced the same problem and what it’s impact was.
Figure 27. Using the Find Potential Duplicates action reduces friction in the process.
4) Be nice to feed users by avoiding subscribing others. Many people manage their work item information stream using the news feeds rather than relying on e-mail subscriptions. The feeds provide filters so events in the repository can be limited to subsets such as “Team Events”, “My Pending Approvals” and “Messages at Me”. When a user is subscribed to a work item, an e-mail is sent to the user whenever the work item is changed (depending on user configuration). Thus, subscribing someone else to a work item may generate more e-mail for the person than they want. When bringing a work item to another person’s attention, it is often better to use an @user reference in a comment than to adding another user as a subscriber. When the @user reference is made, the user is notified through the feed filters and can get a single e-mail for that reference (depending on user configuration), then that user can then decide whether they want to subscribe to the work item or simply reply to the @user comment.
Figure 28. Using an @user reference is the best way to inform another user about a work item change.
For more information on using feeds, see Getting your feet wet with feeds.
5) Think small. Be fine-grained, task-oriented and component-specific. A work item should be a contained and manageable unit of work. Work items should either be a collection of smaller items or should describe single feature or fixing a single problem. Work items should target a single component or part within the component. When a work item does encompass a large change, then a parent work item can be used to plan the large change, while child work items can be used to manage the incremental work. Work items are also easier to manage when they are not organized as a deep tree of items.
For example, if a change involves many updates in a web site, it is better to create work items that describe each change on each page rather than to create one work item describing many changes on many pages. In this case a parent work item could be used to manage the total change — e.g., “[parent] Implement style guideline updates” — while child work items for each change are also created to manage that change: “[Editor] Update required property colors”, “[Query Results] Update table colors”, and “[Quick Information] Add hover pop-up’s”.
Work items are planned for specific milestones, prioritized and assigned within the team. Poorly constructed work items that describe multiple tasks make it more difficult to plan, prioritize and track the work.
6) Use the Force. Let go. When work item customization is performed, whenever possible administrators should use derivatives of the out-of-the-box process templates and out-of-the-box attribute presentations rather than inventing new process configurations and creating custom attribute presentations. The templates provided have been created to optimize and enforce best practices for both agile and traditional processes. For agile processes, the templates have been used to effectively manage many large and highly complex development projects, including the development of Rational Team Concert itself. The templates have been created over many years by contributors who have a great deal of experience creating process configurations. These templates have been proven in real-world self-hosting environments. Over time these templates will be refined, so using the templates provided will give you a clear migration path from prior iterations of the process to new iterations. It is tempting to start from scratch or to make large-scale customizations to build your own custom process; while this is possible and sometimes necessary, it negates the many years of collaborative contribution and real-world experience embodied by the out-of-the-box process specs. Customizations should be designed to improve the efficiency of the team or to enhance auditability; in a process review, work flows, constraints, and presentations which do not improve effieciency or auditability should be called into question. On the other hand, it is reasonable and often necessary to customize the process for the needs of a particular organization to add new attributes, rename or remove attributes, or specify additional constraints. However, In general it is best to stay as close to the hardened process specifications as possible.
Similarly, while it is possible to create detailed custom attribute presentations, the out-of-the-box attribute presentations can present most information effectively, as is proven by years of self-hosting using these widgets. If additional presentations are needed, it is best to create an enhancement request to extend the available presentations and use the existing presentations as substitutes until the desired presentation is available out-of-the-box.
While customization is available, it is often more cost-effective to modify an organization’s procedures to use the predefined processes and presentations than it is to create and maintain a custom process and custom editor presentations.
Conclusion
Work Items are used throughout the collaborative lifecycle of product development. They link artifacts from many roles together to optimize the flow of work across and within teams. Using best practices when designing, creating, and resolving work items brings all contributors and stakeholders together as a more effective team.About the author
Larry Smith is a software engineer working on the web user interface to the IBM Rational Team Concert Change and Configuration Management product. Since joining IBM in 1981, he has worked on numerous projects to improve team collaboration and software developer productivity. Larry can be found at websmith@us.ibm.com.
Copyright © 2011 IBM