LG 3-2 issue with wording and relevance levels
gernotstarke opened this issue · comments
Here's the current version of LG 3-2:
It mentions (R1,R3) in the title, but does NOT give any hints which of its parts are R1 or R3.
I suggest to make the first part ("are able to") R1, and the second ("know that various properties...") R3
LG 3-2: Describe and communicate software architectures (R1,R3)
Software architects are able to:
document and communicate architectures for corresponding stakeholders, thereby addressing different target groups, e.g. management, development teams, QA, other software architects, and possibly additional stakeholders
consolidate and harmonise the style and content of contributions from different groups of authors
know the benefits of template-based documentation
Software architects know that various properties of documentation depend on specifics of the system, its requirements, risks, development process, organization or other factors.
These factors impact:
whether written or verbal communication should be prioritized
the amount and level of detail of documentation needed at each stage of development
the documentation format
the accessibility to the documentation
formality of documentation (e.g. diagrams compliant to a meta model or simple drawings)
formal reviews and sign-off processes for documentation
Software architects are aware of these factors and can adjust the documentation characteristics according to the situation.
+1
+1
I would very much like to reformulate and move the first two points of the second section ("whether written or verbal communication should be prioritized + the amount and level of detail of documentation needed at each stage of development") to the first section.
Maybe like "(are able to) ... explain and implement measure supporting the convergence of written and verbal communication, and balance one against the other appropriately"
The "depending on the amount and level of detail needed at each stage of development" I would omit as this not only depends on the development stage but also on the context (security/safety critical, development process, experience of developers, ...)
Otherwise I agree that the first section should be R1, the second R3.
at first, I add the relevance indicators.
@alxlo your comment actually is another change - I'll update the LG accordingly within the same issue to keep things simpler (usually we like SoC within issues...)
Concerning "the amount and level of detail of documentation needed " - I suggest to remove the second part of that sentence only. Therefore:
"these factors impact:
old: the amount and level of detail of documentation needed at each stage of development
new: the amount and level of detail of documentation needed
"Diese Faktoren beeinflussen:
alt: * Umfang und Detaillierungsgrad der in jeder Entwicklungsphase benötigten Dokumentation
neu: * Umfang und Detaillierungsgrad der benötigten Dokumentation
@alxlo concerning "explain and implement measure supporting the convergence of written and verbal communication, and balance one against the other appropriately"
I re-ordered sub-topics within the LG, here's the result:
Software architects are able to (R1):
* document and communicate architectures for corresponding stakeholders, thereby addressing different target groups, e.g. management, development teams, QA, other software architects, and possibly additional stakeholders
* consolidate and harmonise the style and content of contributions from different groups of authors
* develop and implement measures to support the convergence of written and verbal communication, and balance one against the other appropriately
Software architects know (R1):
* that various properties of documentation depend on specifics of the system, its requirements, risks, development process, organization or other factors.
* the benefits of template-based documentation
...
I renamed the issue to better reflect its content.
@alxlo - for future issues I suggest to open new issues for additional changes...