odoo_mqtt/DOCUMENTATION_STRATEGY.md

Dokumentationsstrategie (Root)

Stand: 2026-02-19
Ziel: Root-Dokumente schlank halten, fachliche Details in die Modul-Dokumentation verlagern.

1) Source of Truth

IoT Bridge (Runtime)

• iot_bridge/README.md – Gesamtüberblick, Betriebslogik, Konfiguration
• iot_bridge/ARCHITECTURE.md – Architektur und Datenfluss
• iot_bridge/DEVELOPMENT.md – Setup, Tests, Debugging
• iot_bridge/API.md – Einstieg + Verweis auf OpenAPI (/docs, /redoc, /openapi.json)

Odoo Addon (open_workshop_mqtt)

• extra-addons/open_workshop/open_workshop_mqtt/README.md – Funktionsumfang und Bedienung
• extra-addons/open_workshop/open_workshop_mqtt/API.md – Event-API und Odoo-spezifisches Verhalten

2) Rolle der Root-Dokumente

Root-Dateien enthalten nur noch:

• Projektweite Orientierung
• Deployment-Einstieg
• Historische Entscheidungskontexte (klar als „historisch“ markiert)

Root-Dateien enthalten nicht mehr:

• Vollständige API-Schemata
• Detaillierte Implementierungsanweisungen auf Dateiebene
• Duplicate Content aus iot_bridge/* oder Addon-README/API

3) Aktueller Status der Root-Dateien

• DEPLOYMENT.md → aktiv (kurzer operativer Leitfaden)
• IMPLEMENTATION_PLAN.md → aktiv (kompakte Statusübersicht + nächste Schritte)

Historische Request-/Teilplan-Dokumente liegen unter docs/history/:

• docs/history/FEATURE_REQUEST_OPEN_WORKSHOP_MQTT_IoT.md
• docs/history/FEATURE_REQUEST_DEVICE_STATUS.md
• docs/history/IMPLEMENTATION_PLAN_DEVICE_STATUS.md

4) Pflege-Regeln

1. Änderungen zuerst in Code + tests + Modul-Doku.
2. Root-Doku nur aktualisieren, wenn sich Prozess/Status/Navigation ändert.
3. Jede Root-Datei mit Datum und Status versehen.
4. Keine langen Codebeispiele im Root, stattdessen Link auf das zuständige Modul-Dokument.