PicturePaintsThousandWords

From SPA Wiki

Contents 1 Ot2004 WS11 - A Picture Paints a Thousand Words... Or does it? 1.1 Background 1.2 Session Objectives 1.3 Session format 1.4 Conclusions

Ot2004 WS11 - A Picture Paints a Thousand Words... Or does it?

MattStephenson - Royal & Sun Alliance

StephenHutchinson - Accenture

If you would like to discuss this session, please use PicturePaintsThousandWordsDiscussion - Thanks

Background

Good architecture or design documentation is really important for many reasons, but is often poorly done. Documentation is often laden with meaning for the author, but a mind-boggling tangle of lines and boxes to the uninitiated.

Many of us who have been involved in software development for any length of time will, at one time or another, have been guilty of producing bad documentation. Most of us will also have been unfortunate enough to be on the receiving end of bad documentation.

The problem when we produce bad documentation is that we often don't realise that it is bad. Because we have lots of background knowledge that we could draw on when writing it, we think that the documentation says everything it needs to say, and that it says it well.

The problem when we receive bad documentation is that we often go back to the author and say "this is bad, I can't use it. Go away and make it better". Of course, the author can't really respond to that request because they already thought the document was good! What we really need to be able to tell them is why it is bad, and what we need the documentation to give us.

Session Objectives

The session had three primary objectives.

1. To consider how to to spot when architecture documentation is bad and unusable.
2. To consider how to articulate the specific problems with a piece of documentation.
3. To consider ways of helping the author of that documentation produce something that is usable (and that author might be you!).

Session format

The session consisted of two exercises.

The first discussed precision or lack thereof in architecture and design documentation. The second exercise considered views, and the common problem of trying (and usually failing) to produce a single diagram that tells all things to all audiences.

In the first exercise, we suggested that there are many reasons why an author would produce a document that is imprecise. Firstly, the author might not realise it is imprecise, because he/she has a load of other information in their head that they draw on when looking at the documents. To them, the document speaks volumes.

Secondly, the document might have been intended as an aide memoir for the author. Thirdly, it might be a prop to help the author explain something to someone else.

Imprecise documentation is acceptable in the second and third scenarios, provided it is only used for those purposes. The problem arises when an attempt is made subsequently to use the documentation for a different purpose, such as education of team members without the supporting explanations from the author.

The teams in this exercise considered a bad architecture diagram and were asked to produce an interpretation of it, with some assumptions that helped them make that interpretation. We then asked the teams to suggest things they would do to the diagram in order to make it more precisely describe the interpretation they came up with.

In the subsequent discussion amongst the whole group, we captured the improvements that were suggested. They were:

• Differentiate overloaded symbols (i.e. where the same symbol appears to be used for different purposes).
• Differentiate between internal and external system elements explicitly.
• Put labels on the arrows!
• Precise (and better) naming of diagram elements.
• State the level of precision that has been attempted.
• If the diagram is intended to show sequence, then annotate it accordling.
• Use standard (or at least consistent within your organisation) diagramming notations.
• Put a title on the diagram indicating the type of diagram.
• Put a key on it (especially if you are using non-standard notation).
• Consider producing a glossary of terms / data dictionary.
• State whether it is a picture of software or a "business" diagram.
• Consider using textual information if appropriate (or in support of the diagrams).
• State the audience (this point was not unanimously accepted as a good thing in this exercise, but the person who suggested it did give a compelling argument).

In exercise two, we discussed the problem we often face, which is that we are often tasked with producing a single (often single-page) diagram to explain the architecture of our system to all and sundry. We suggested that this was a bad thing, because what usually happens is that the diagram fails to do a decent job of communicating with any of the audiences.

Once again, the teams were given an architecture diagram to discuss. The author of the diagram had been asked to show various types of information so that there was a single document that could be used to show many things.

The teams were asked to produce a list of the different views that could be extracted from the diagram as separate documents, to improve the clarity of the communication of each view to its intended audience.

The list of views produced was:

• Use Case realisation.
• Component Diagram (a.k.a. in this context as a System Dependency Diagram).
• Activity Diagram.
• Business Process Flow.
• System Context.
• Information Model.
• State Chart (which may have been a better representation for the apparent sequence information in the diagram).

We also drew some conclusions from this exercise. Namely:

1. One size very definitely does NOT fit all!
2. You need to produce multiple views with clearly defined purposes - know who and what each document is intended for.
3. That makes it easier for you to make each view precise.
4. Views make it possible to fit all information on (the suite of views).

However, there were a couple of provisos we had to add:

1. You do have to have the discipline to keep all of the views consistent with one another.
2. Don’t assume that a diagram is always the most appropriate medium. Use text to convey detail.

Conclusions

We finished the session with a couple of key messages:

From exercise one, we concluded that if you aren’t going to be there to explain your diagram to everyone who might try to read it, make it precise.

From exercise two, we believe that you must consider the uses and audiences of your documentation and tailor views accordingly.

Back to OtTwoThousandAndFourOutput.