[12:04] In den vergangenen Tagen habe ich mich intensiver mit UML und Aktivitätsdiagrammen in PlantUML auseinandergesetzt, um unser Wiki mit Aktivitätsdiagrammen zu bereichern. Dabei gestaltet es sich nicht immer einfach, den Beschreibungstext so knapp und präzise wie möglich, aber dennoch so umfassend wie nötig zu verfassen. Dies wirft die Frage auf, ob wir in den Beschreibungen Hinweise und Verweise auf die von uns verwendeten Tools integrieren möchten.
Die Entscheidung, ob du die von dir verwendeten Tools im Beschreibungstext zu einem UML-Diagramm im Wiki detailliert erwähnen solltest, hängt dabei von verschiedenen Faktoren ab. Hier sind einige Überlegungen:
1. Zielgruppe:
- Wenn deine Zielgruppe technisch versiert ist und von den spezifischen Tools profitieren könnte, könnte es sinnvoll sein, diese zu erwähnen.
- Bei einer nicht technisch orientierten Zielgruppe könnte der Fokus eher auf der allgemeinen Systemarchitektur und Funktionalität liegen, und Tool-Referenzen könnten weniger relevant sein.
2. Dokumentationszweck:
- Überlege, welchen Zweck die Dokumentation erfüllen soll. Wenn sie als Leitfaden für Entwickler oder als technische Referenz dient, können Tool-Referenzen nützlich sein.
- Bei Dokumentationen für allgemeinere Zwecke könnte es ausreichen, sich auf die Gesamtfunktionalität und Struktur zu konzentrieren.
3. Separate Dokumentation:
- Wenn die Details zu den verwendeten Tools umfangreich sind, könnte es sinnvoller sein, diese Informationen in einer separaten Dokumentation zu speichern und im Wiki darauf zu verweisen.
4. Unternehmensrichtlinien:
- Überprüfe die Richtlinien deines Unternehmens in Bezug auf Dokumentation und ob spezifische Tools in Beschreibungen aufgenommen werden sollten.
In vielen Fällen ist es eine gute Praxis, klare und prägnante Beschreibungen zu verwenden und detaillierte Informationen zu Tools in einem speziellen Abschnitt oder in separaten Dokumenten zu speichern. Dadurch bleibt die Hauptdokumentation leicht verständlich, und Interessierte können bei Bedarf weitere technische Details einsehen.
Tags: #notiz #uml #plantuml #dokumentation