Yesterday, I was at Berlin for the first day of the Software Architecture Summit. I have participated on one of the workshops – Diagrams for Modern Software Architecture and I will simply put my notes about it, hoping that it will become a nice article 🙂
Diagrams for Modern Software Architecture
What is important about Software architecture is summed in the following:
The source code does not tell the whole story & the source code is the best documentation;
Pretty much, noone likes to write documentation, but it is a must in every project. Thus, it should be there. These are the 7 rules for good documentation:
1. Write from the reader’s perspective.
2. Avoid unnecessary repetitions.
3. Avoid ambiguity. Explain your notation.
4. Use a standard structure.
5. Define justifications for decisions.
6. Keep documentation up-to-date, but not too up-to-date.
7. Verify documentation for their suitability for use.
Easy to say, tough to do. But all of them make sense, once they are explained. Another take home message was – “Use less UML elements, but make sure that you use them correctly!”.
Furthermore, the following GOes and NO GOes, concerning diagrams were introduced:
Last but not least, if you are building a diagram, make sure that you give it a mission statement. It is for you, as a documentation developer (yup, there are such people and this is a real job!) and it would help you to remember it.
More useful tips about diagrams are available here:
Visualizing Software Architecture
Conception of Software Architecture (In German)
Open Source tool that uses simple textual descriptions to write UML diagrams