Software Architecture tips II - Illuminate don't detail

Illuminate don't detail

Another common problem is that of "wallpaper" diagrams, a kind of "one diagram to rule them all approach". This leads to one diagram which is normally static, that shows all the components in the system and attempts to show multiple axis of interest (protocols, deployment, technology).

It's wallpaper as people then proceed to stick it on a wall and refer to it in all conversations - the issue being that no one apart from the author knows what it means (and sometime even they don't), its notation is secret, and its not normally kept up-to-date.

But prehaps the worst sin is that the diagram is just too complex! it is better to have a few simple diagrams that show a system from different views (static, dynamic, deployment) and a few key scenarios (startup, failure, major business cases etc) - so each diagram should illuminate a design approach and decisions taken, rather than trying to get all the detail on one page.

Another advantage of the "illuminate don't detail" approach is that it leaves space for other decisions to be made later, as trying to detail everything at the start leads to design decisions being made that are not based on delivering a user story, but on the need to nail down everything.