Skip to main content

TRG 1.05 - Architecture Documentation

StatusCreatedPost-History
Active01-Aug-2024
Draft26-Mar-2024Transferred from Release Acceptance Criteria into TRG

Why​

Proper Architecture Documentation is necessary to support architects and operation teams for their decisions making processes and operative tasks. It therefore provides information like context, integration interfaces and intended usage of the component. We follow the good practice to document the Architecture of components.

Description​

Eclipse Tractus-X is using the arc42 documentation template. If you are not yet familiar with it, see arc42.org for an introduction and guidance.

In order to pragmatically start or update your Architecture documentation, consult arc42. Architecture documentation must be maintained in a directory named /docs/architecture in the leading product 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 must be stored in the folder: /docs/architecture
    • It is up-to-date for every release
    • English is a must
  • The /docs/README.md describes shortly what documentation is available

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)