Blog Archives

Storytelling is increasingly being recognised as a powerful communication tool in the business arena.  Business leaders and authors such as Tom Peters, Peter Senge and Stephen Denning are encouraging the use of storytelling to communicate leadership concepts and pass on organisation knowledge.  They're referring to stories more in the manner of Aesop's fables to communicate a business or leadership concept in a creative and memorable way.  However, I think we in IT would benefit from the discipline of storytelling.  I see a good requirements document as being about communicating the story for meeting the business need. 

The Context Diagram as an Introduction to the Story

The context diagram is derived from the (arguably) outdated data flow diagramming (DFD) technique.  The context diagram is another name for the DFD Level 0 diagram.  The uppermost diagram in a set.  The intent is to show the system in question as a black box in its environment.  In many analysis and requirements templates there is still a request for context diagrams to be included.  This is despite context diagrams harking from the afore mentioned DFD days, when today UML is the notation in vogue.

Although I'm generally a purist, I have been convinced that representing the system as a white box with a low level of detail provides the best … context, for the system.  Below is a traditional context diagram, followed by my take on a context diagram that is useful for setting up the story for an end user.

A traditional DFD Level 0 (context) diagram

My version, using a combination of UML symbols and some more colourful people icons.

Organising the Documentation Into Domains

After setting the scene via a context diagram, you should tell your audience how you expect to lay the document out.  At the Australian National University Shayne Flint, teaches the separation of concerns when analysing a system based on the work of Stephen Mellor and Sally Schlaer.  By separating concerns when undertaking software engineering you improve the software's understandability, portability and resuse.

Different concerns are documented as domains (UML package diagrams).  I mostly use concerns as subsystems, but they can also refer to concerns that apply universally across the application, such as persistance or security.  Later on, concerns can be used to document aspects of implementation such as an execution environment (Flint and Boughton, access 2010).  Below is a domain model from Flint and Boughton's article Executable/Translatable UML and Systems Engineering.