WS11		OT2004 Session A Picture Paints a Thousand Words - Or does it?
		Documentation and communication of a system's architecture is important for many reasons, but often poorly done. What are the common pitfalls and how can they be avoided? Tuesday 30 March, 14:45
		workshop -    75 minutes
		MattStephenson StephenHutchinson
Session results	When available, can be found at PicturePaintsThousandWordsOrDoesItSessionResults??
Abstract	All too often the documentation for a system's architecture consists of "The Diagram", which is a complex web of lines and boxes laden with meaning to the initiated, but a head-spinning tangle to others. Recording and communicating the architecture is important for many reasons but is often poorly done. What are the main pitfalls and how can they be avoided? Some of the common problems that will be addressed include (but are not limited to): "One size fits all" - There is often little or no thought given to the different audiences that may need to consume the architectural documentation, so a single "view" of the architecture is presented, which doesn't tell everyone everything they need to know. "A picture paints a thousand words" - The importance of textual information is often underestimated in documentation. Sometimes the diagrams are over-simplified to the point of being inaccurate, or over-complicated in an attempt to cover everything. Putting some of the detailed information into textual form would help either approach. "It's obvious what the lines mean!" - Many architecture diagrams are ambiguous. For example, how many diagrams have you seen where the lines connecting the boxes are unlabelled? Additionally, some of the lines represent specific data-flow while others are used to represent general relationships between system components. Architecturally speaking, it is often the case that the "lines" are more important than the "boxes", but they are neglected. "The all singing, all dancing diagram" - Too often an attempt is made to keep the architecture documentation to a single "diagram". This usually leads to one of two things. EITHER an over-complicated diagram that is confusing in its mixing of software and hardware, logical and physical, etc., OR a diagram that has important information left out because it was difficult to reflect it whilst confined to a single page. This workshop will help the delegate to recognise the difference between good architecture documentation and bad.
Audience	This workshop is appropriate for any delegate who has an interest in good architecture documentation, or has been on the receiving end of bad. The session will also be valuable for any architect who has produced architecture documentation by isn't happy that they are doing it as effectively as they might be able to. Finally, the workshop's effectiveness will be enhanced by the attendance of seasoned architects who have a good handle on what constitutes good architecture documentation - their input will be invaluable.
Benefits	Those delegates who find themselves on the receiving end of bad architecture documentation will be able to use the output from this session to influence their architects to do something different. They may be more successful if they can complain about specific flaws rather than with a general "I can't use this documentation". The architects who feel they need help will be able to take away the outputs and apply them to their own projects, helping those projects to be more successful by having architecture documentation that can be understood by many audiences. The experienced architects who feel they already have a good handle on these outputs will get to show off their skills and leave with the warm feeling of having helped some other architects to do a better job.
Materials	The flawed architecture documentation. Examples of improved architecture documentation.