Agile Architecture Documentation Workshop
Revision as of 22:41, 10 December 2012 by Clarman
1-2 days (for most systems, if this is the first agile arch doc workshop, 2 days is more realistic; later workshops can be 1 day)
In this workshop, people apply agile modeling and documentation techniques to document their software architecture. We take an "N+1" view-model approach, creating the logical view, deployment view, and more, and also write "technical memos." This is done "at the walls" in a small teams, sketching on vast whiteboard spaces, in a wiki, and with video capture of Q&A sessions for different architectural views and technical memos. As will be seen, not only is the architecture documentation created, but the workshop is also a context for learning about the architecture. For example, different sub-groups are working in parallel on different walls, one doing the logical view, one doing the deployment view, and so forth. We practice "show and tell" visiting other walls, and in this way learn from each other. Another example: we do pair writing and pair review of different technical memos, and learn from each other.
The output is an N+1 view model of the architecture combined with technical memos, captured in wiki pages, videos of Q&A sessions related to views and technical memos, and perhaps equally important, learning and an increased shared understanding of the architecture that has been documented.
This workshop can also be combined with the definition and organization of a self-study plus Q&A mentoring system for new hires to your company, to speed and improve the architectural knowledge of your staff.
Methods of Education
primarily workshop coaching "at the walls"; some minor discussion.
- this can only be for one product group.
- attendees should be able to contribute to documenting the architecture (i.e., they know something in detail about it, and some people at the workshop have real breadth and/or depth of understanding)
- but not all attendees need be experts -- a mixture of knowledge-levels is useful so that some people are learning more about the existing architecture (i.e., use the agile doc workshop to increase learning in the group)
This is an immersive workshop. No prior knowledge is absolutely required.
There are not strict prerequisites. However, people who know basic UML notation or who have attended any one of the follow courses will be better prepared to take full advantage of this workshop:
- Applying UML and Patterns: Hands-on Mastery of OOA/D, Agile Modeling, & Patterns -- & with TDD introduction
This is not a course per se, but a product-specific workshop to document the existing architecture. Nevertheless, in the context of the workshop, participants will learn more about visual modeling, and new ways to model and document.
Environment - Room, Tools, Texts
- If this is a large group (e.g., more than 10 people), we will need an especially large modeling room with truly *massive* whiteboard areas, in which each group uses 2 of the 4 walls.
- lots of fresh black whiteboard marker pens
- whiteboard erasers
- 1 package of "flipchart" paper
- 1 roll of "painters tape" or "masking tape"
- 1-2 computer projectors and 1-2 project screens (or big white walls we can project on to)
- wiki, with all participants having access
- 1-2 video cameras with tripod, storage in each for at least 5 hours of video
- Also, read and organize for this: Course Environment - Workshop Style7