Component Capabilities
This guide describes the most fundamental parts of component capabilities. It also includes a flowchart of component capabilities updates and a list of attributes sometimes mistaken for component capabilities.
Specific add-ons, such as those to ensure safety compliance, may be needed in the future.
Intended for
Software engineers, scrum masters, and product owners.
"What" and not "How"
Component capabilities shall describe what the component "can do" for anyone who wants to understand its capabilities. The capabilities should be described in a short format focusing on the "what," while the "how" is defined in architecture and detailed design documentation.
Bullet lists are a common format in a component capabilities file since they usually list all supported functionality shortly and concisely.
Implemented and verified functionality
Capabilities are internal documentation of what a component can do in its current state. Future feature support should not be written in a component capability.
A component capability should only state verified functionality. Hence, the component capability updates can be merged only after the functionality is tested.
Before closing a feature, the newly implemented functionality shall be documented in the corresponding component capabilities file.
Input and consumers
Input to a component capability is a feature description and the feature's acceptance criteria. Examples of consumers of a component capability are developers, new employees, testers, product owners, and architects.
Component capabilities may also serve as input to product capabilities and end-user documentation.
Traceability, reviewers, location, and filename
The component capabilities are documented in an .md file named "Capabilities.md", located in the repository of the component source code.
This file is part of the component's lifecycle. When new features are added to a specific component version, the capability files must be updated based on the corresponding version of the component repository.
When the component capability is updated, it should be merged with a pull request linked to the feature or any of its child work items. This will provide enough traceability from the component capability perspective. In other words, by linking the pull request to the feature or any of its child items, the capability update can be fully traced to the entire chain of requirements (system requirements – epics – features – user stories – tasks – source code), and the related test cases.
The product owner should review the pull request, including the component capabilities update.
There is no direct traceability link between component capabilities and threat models. However, there will be a traceability path between threat models and component capabilities when the threat models reference features or bugs.
Architecture design and detailed design documentation have no explicit traceability to component capabilities. The relationship between component capabilities and architecture and detailed design descriptions is only realized through features defined with architecture and detailed design descriptions as input.
Note: A pull request in Git repositories corresponds to a check-in in Team Foundation Version Control (TFVC) repositories.
What is not a component capability?
- A component capability is not a product requirement; it's written as the output/outcome of the implementation. As input to implementation, system epics, epics, and features will be used (these work items replace the previously used product requirements). See the workflow visualization below for a better understanding.
- Component capabilities should not be confused with architecture or detailed design documentation. They are written as the outcome of implemented and tested features or bug corrections, and these work items were potentially defined in an earlier step with architecture and detailed design documentation as input.
- Software development kit (SDK) documentation is not part of component capabilities.
- In general, unsupported functionality should not be mentioned in a component capability. However, exceptions can be made if they help the reader understand the product's current state.
Workflow diagram
