Product Capabilities
Product capabilities describe what the product “can do” for anyone who wants to understand its capabilities. They represent the product's property and are updated throughout its lifecycle through multiple releases.
This guide describes the most basic parts of product capabilities. Specific add-ons, such as those to ensure Safety compliance, may be needed in the future.
Intended for
Product owners, test leads, architects, and product managers.
Purpose
Why do we write product capabilities?
- Product capabilities documents serve as one consolidated place to describe high-level product capabilities. Without product capabilities, this kind of documentation would be scattered in epics, features, and the component's capabilities. It would be difficult to get an overview of the product's capabilities, and existing documentation would be too low-level.
- Product capabilities are foremost intended for product managers, owners, and architects to understand whether the product meets expectations and for developers, testers, and new employees to get an overview of the current state of the product. Product capabilities also provide traceability to product tests. By reading product capabilities, the reader is informed about what has currently passed product tests. The test cases can also be analyzed in the associated product test suite.
Definition and clarifications
"What" and not "How"
Product capabilities shall describe what the product “can do” for anyone who wants to understand what the product is capable of.
The capabilities shall be described in a short format focusing on the "what" (without detailing internal interfaces/functionality that are not important to know about when using the product), while the "how" is defined in architecture and detailed design documentation. A bullet list is a common format in a product capabilities file since it usually lists all supported functionality briefly and concisely.
End-user/customer perspective
Product capabilities are written from an end-user or customer perspective. This means that product capabilities state what the end user can do when using the product in its current state, or in other words, which capabilities are interesting for the end user to know about to exploit the product fully.
Functionality support is described at a very high abstraction level. For example, the control platform's capability to receive and use configuration files sent from the engineering tool is not stated in a product capability (but rather in the component capabilities). That would be too much "under the hood." Instead, the product capability would state that the product supports the control execution of logic using Structured Text since it is important for the end user to know when using the product.
The current state of implemented and verified functionality
Capabilities serve as internal (ABB) documentation of what a product can do in its current state.
Future functionalities should not be written in a product capability. Only verified functionality should be stated in a product capability. Hence, the product capability updates can only be merged when the functionality has been tested.
Before closing an epic, the newly implemented functionality shall be documented in the corresponding product capabilities.
Structure - what abstraction level defines a product?
A product is the abstraction level above components and should be aligned with what the architecture documentation defines as products. Therefore it is important to involve the architect When defining a new product in this context.
Traceability
The automated product test cases are in the same repository as the product capabilities. They shall use the same naming conventions to make it easy to understand what test cases have been executed to verify each capability. If manual tests have been executed, a link to the location of their descriptions shall be provided.
Product capabilities, architecture documentation, and detailed design documentation should follow the same naming convention to make the relationship between the content of the different artifacts easy to understand.
"Traceability by naming convention" means that if, for example, "AC800M Execution Service" is a defined product in the architecture documentation, the exact same name must be used throughout the rest of the documentation and product test framework.
While traceability by naming convention in product capabilities, detail design documentation, architecture documentation, and product tests is considered enough today, it will be investigated if the traceability should be strengthened with product IDs in the future.
A product capability should also provide a link (linking can be done in different ways depending on stream conventions) to the location of the architecture design and detailed design documentation to make it easy for readers to find if they are interested in further reading.
What is not a product capability
- A product capability is not a direct translation of traditional product requirements. Although product capabilities often will be drafted in temporary branches in parallel with implementation, the final merge of a product capability update is done after the capability has been implemented and tested. As input to implementation, system epics, epics, and features will be used (these work items are replacing the previously used product requirements). See the workflow visualization below for a better understanding.
- A product capability should not be confused with architecture or detailed design documentation. Product capabilities are written as an outcome of implemented and tested epics or bug corrections and these work items were in an earlier step potentially defined with architecture and detailed design documentation as input.
- In general, unsupported functionality should not be mentioned in a product capability. However, exceptions can be made if they help the reader understand the product's current state.
- A product capability does not describe full system functions but is limited to the product's contribution to those system functions.
Usage/Workflow
Input
Input to a product capability is an epic description and the epic acceptance criteria. Although epics should be sufficient input for writing product capabilities, sometimes component capabilities can be used as additional input when writing product capabilities (often, product capabilities refer to component capabilities for more details.)
Reviewers
The product capabilities are written in Markdown (.md) files in the same repository as the product test source code. When the product's capability is updated, it should be merged with a pull request 1 linked to the corresponding task for the update. Through the parent-child links, the task is traceable to the corresponding epic (via user stories and features).
The pull request including the product capabilities update should be reviewed by the product manager, product owner, and the product tester (product capabilities are often written in collaboration between the product owner and product tester). The architect and relevant scrum masters are informed as optional reviewers.
Consumers
Examples of consumers of a product capability are product managers, product owners, and architects who agree that the implementation meets expectations. Consumers can also be developers and new employees who understand the current state of implementation on a high level. Finally, testers (especially on the product test level) consume product capabilities to understand what high-level functionality has already been tested.
Product capabilities may also serve as input to end-user documentation.
Workflow/traceability diagram
As seen below, input to implementation and documentation starts with system epics, which are then refined into smaller, more detailed work packages. The information input to a product capability comes mainly from an epic since they have corresponding abstraction levels. However, there will be tasks (small work packages) to update the product capabilities and track the actual progress of the update.
Links
Footnotes
-
Pull requests in Git repositories correspond to check-in in Team Foundation Version Control (TFVC) repositories. ↩