SoldHowToDescribeExplainAndJustifyYourArchitecture
From SPA Wiki
Contents |
WS3 - Sold! How to Describe, Explain and Justify Your Architecture
[Back to SpaTwoThousandAndEightOutput]
Architectural Description Content Lists
Team 1
-> AD for agile?
Contents of ADs:
- Scope/intent [agile(%2b)]
a. Why?
b. What system is the AD describing?
c. Who is audience?
d. Where does architecture fit into whole system?
e. Info about problem domain
f. Where and how is the system used?
- Baseline - which set of requirements [agile(-)]
- Description of system with interfaces [agile(%2b)]
- Identification of components [agile(%2b)]
- Allocation of requirements to components [agile(%2b)]
- Internal interfaces between components [agile(%2b)]
- Non-functionals (security, performance, ...) [agile(%2b)]
- How am I going to integrate system? [agile(%2b)]
%2b Appendices
Questions:
- Who reads AD?
- Who approves it?
- New developers?
- When do you write AD?
- before/during/after?
- Why AD?
- New developers
- Communicate problem domain and understanding
- define system boundaries
- Import development plan
Team 2
- Intro to document
- Purpose - Stakeholders - How this doc evolved
- Why we're doing this project
- Who the system users are %2b what they're doing (key functions)
- User-friendly physical description
- Key functional and quality requirements
- Current versus planned architecture
- Expected system evolution
- Boundary and interfaces
- 'Physical' software/system view (BD's etc.)
- . Domain model/descriptions
- . Key design decisions (%2bwhat/why we rejected)
Team 3
Context is initial document for persuading people to pay for the system:
- Management Summary (1/2 page)
- Content
- Big conceptual diagram of system context
- High level scope and requirements
- [Other details according to interest]
- Questions and Answers
- Glossary
All of this should be in stakeholder language (not in "architectural representations")
Team 4
Mandatory Sections:
- Scope
- Audience
- Status
- Stakeholders
- Functional view
Optional Sections (selected according to system and stakeholders):
- Purpose
- Scope
- Requirements Overview
- Glossary
- Other views
- Other system qualities
- System environment
- Goals
- Constraints
- Design Principles
- Timescales / Migration
Architectural Description Content Notation and Tools
Team 1
UML based approach, possibly customised for domain (e.g. profiles).
- Clarify understanding via models
- Choose UML artefacts carefully
- Achieve traceability with a requirements tool
- Allow for model organisation evolving as architecture moves into design
Publish outputs of modelling to
- Wiki sites (e.g. Confluence)
- Work and PPT (but may need access control)
- As-Is from the modelling tool
Paper and pencil still useful when thinking.
Need connectivity between Document Store, Requirements Tool, UML Tool down to the code, with publishing to MS Office, web etc.
Team 2
Key message is Keep It Simple Stupid (KISS)
- Word
- Visio
- Powerpoint
- Excel
- Jira (e.g. design decisions)
- Subversion
- Whiteboards
Would like a simulation and animation tool, although haven't used one.
Need to cross reference requirements to solutions (Excel?)
Wouldn't use UML as it creates communication problems.
Need to couch the AD in the language of business rather than of technology.
Team 3
Tools and techniques would be MS Word and Wikis due to UML not being portable between tools and environments.
On balance, the tools and techniques are worth the cost. [Why?]
Would make extensive use of word processing as a communication medium, but versioning is a problem in this case.
If pushed for time, then a whiteboard and MS Word would be the basic approach.
Team 4
- A "nice" drawing tool, meaning one that is based on a well defined notation but that does not enforce the notation at all times (i.e. allows a "relaxed" notation mode). Versioning of the models and HTML export would be key requirements.
- Wiki site
- Screen sized change units;
- Allows for intelligent decomposition;
- Needs to provide ability to generate PDFs;
- Provides version control at the page level.
- Mind mapping tool
- Allowing HTML export
- Providing versioning
- Animations (again providing versioning)
Review management is an important quality that all of the tools should offer.
Socialising the AD
- Launch it to stakeholders
- Talk (F2F and interactive) is the main thing
- PPT is a vehicle for this
- This is a transient/push activity
- Overview session followed by detailed ones with specific groups
- Explore it (stakeholders can...)
- Living repository (e.g. confluence)
- Project status
- This is a persistent/pull activity
- Change
- Re-present and re-launch
- Subscribe to persistent form (watch list/RSS)
Need to maintain a selling mentality
[Back to SpaTwoThousandAndEightOutput]
