- Created by Robert Reiner, last modified on 13. Jun 2020
projectdoc Toolbox
Components are part of a view on a system. A component may refer to a enclosed element or to a complete system of its own.
- ID
component- Suite
- Documentation Type
- Categories
- Tags
Components are modules of the system.
For larger systems a component document may describe the component briefly and link to a space with detailed information on the component. This is especially true in case the component has its own release cycle.
Components within the release cycle of the system may provided very detailed information as subdocuments of type view, architecture aspect, etc.
Properties
The document type component provides the following properties:
Please note that only information about specific properties is provided here. Common document property used by all document types are documented by Document Properties.
Level
Define the depth of the containment hierarchy for this component.
This value is typically derived automatically by the depth of this document within its component documents tree.
Reference
Add references to information on external systems here.
Sections
Description
Give a brief description of the design and the usage of the component.
In contrast to the short description this section may contain any formatting and text elements required. This section is intended to be transcluded by other documents that refer to this component.
May contain a context diagram centred on the component, but keep it very small. Also note that in case such a diagram is included, make sure to include it in every component description. Documents may transclude the abstract information from different components. Nonetheless these documents should appear monolithic to the reader. If in doubt, add the context diagram to the view section.
Summary
Provide an overview description of the component. This summary should cover every aspect of the component from a higher level.
The summary is intended to be transcluded in overview documents.
Properties
Provide a list of configuration options of the component.
Required Properties
List properties that are mandatory to run this component.
Optional Properties
List properties that are optional to run this component.
Use Cases
Use cases allow to define how the component is used. This section may also show use cases where the component plays only a small role. Add a reference to a use case document for each identified use case.
Quality Scenarios
Quality scenarios document the important quality aspects of the component. Add a reference to a quality scenario document for each important quality of the component.
Architecture Aspects
With architecture aspects the team documents aspects that have impact on all components of the system. List the aspects that are most important for the component.
Views
Components are important to the system. To explain their construction, runtime behaviour or deployment use view documents.
This section may also contain a context diagram.
Interfaces
List how other components may communicate with this component over its interfaces.
Provided Interfaces
List the interfaces provided by this component.
Required Interfaces
List the interfaces required by this component.
Artifacts
List the artifacts that manifest this component.
Subordinate Components
List subcomponents within this component.
Related Components
You may want to Reference components that are associated with this one. This makes it easier for readers to get information about those collaborators.
But this list of references is not restricted to collaboration. You may also reference components that are connected to this component in any other way. For instance, a component may be replaced by other components that implement the same interface. Listing those components may be very helpful for teams having the task to assemble a system.
This information may be part of the Interface section or have its own section.
Architecture Decisions
A components design or implementation may be based on some architectural decisions. List those that are important to understand the component.
Notes
These are internal notes that are usually not exported and only visible to team members with write access.
But this is not a safe place to store sensible information. It is just a convenience for the reader to not be bothered with notes stored here for the authors for later use. The security level is about suppressing the representation by a CSS style. Therefore consider this as a convenience for the reader, not as a security tool.
The text of notes sections is also indexed.
References
For a document the references section contains pointers to resources that prove the statements of the document.
Often these proofs are not easily distinguishable from further information. In this case you may want to skip the reference section in favour for the resource list.
For further information please refer to References and Resources.
Resources
The resources section provides references to further information to the topic of the document.
This may be information on the internet provided by the resource or information in the team's information systems. Anything the reader of the resource might want to know, may be listed here.
For further information please refer to References and Resources.
Related Doctypes
- Use Case
- Defines a use case of the product.
- Quality Scenario
- Quality Scenarios document required qualities.
- Architecture Aspect
- Document an aspect of your architecture. Something orthogonal or cross-functional like logging, exception handling or configurability.
- View
- Different views on the product help to document the system and its architecture. Typical views are building block, runtime, or deployment.
- Architecture Decision
- Document a architecture decision for an option. This is useful to state the reasons and the options that have been evaluated. Later other team members will have it easier to understand the decision.
- Code
- Describe the codes that are part of the product's API.
- Property
- Properties are part of the configuration options of a system.
- Data Type
- Document a data type for properties and codes.
