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

Here is the list of related document types: