TRG 1.05 - Architecture Documentation

caution

Proposed release date: 30th of March 2024

Status	Created	Post-History
Draft	26-Mar-2024	Transferred from Release Acceptance Criteria into TRG

Why

To provide information like context, integration interfaces and planned usage of the component. The architecture documentation should support architects and operation teams for their decisions and operative tasks. We follow the good practice to document the Architecture of FOSS components. ARC42 is our template of choice.

Description

In order to pragmatically start or update your Architecture documentation, consult ARC42. An "Architecture" folder must be present in the /docs/ folder of your leading repository. Within the Architecture folder the structure of the ARC42 template shall be applied. Follow the guidance to understand, WHAT and HOW to document.

• The Architecture Documentation has to be stored in the folder: /docs/
• Architecture Documentation is available with the software at the same time
• Architecture Documentation is correct and up to date; English is a must
• The documentation is of appropriate maturity to be handed over to any Operations Company with global business practice intentions

Best Practice

• Provide each chapter of the Arc42 documentation as single .md file named after the chapter
• Favor diagrams as mermaid block in .md files directly over image files, where possible
• Have a look to peer repositories within Tractus-X for inspiration
• Anchor a link to your Architecture Documentation within your README.md (see TRG 1.01)
• The Architecture Documentation is in sync with the latest released version of the component. It is checked and updated, once an up-revision is foreseen
• The content is of appropriate maturity, so that any Operations Company with global business practice intentions is invited to use and build on it
• Provide link to documentation as early as possible and mark changes to the previous version (if applicable); expect optimization loops based on feedback