The last user group session may have seen a small turnout, but we did have some interesting discussion about sharing architecture. Here are my notes.
- Architecture document should outline decisions and their implications - get people to sign-up (emotionally and contractually).
- Writing the architecture document provides benefit because you are going through the thought process.
- Who do we need to share the architecture with?
- Who is the audience and what is important to them?
- Development team
- Support staff
- Budget holders
- External test team
- How does the architecture document help these people and what is it that they find useful?
- Should we ask developers to sign-off on the architecture?
- Is "pair architecting" common practice and/or should we do more of it?
- Documents are typically written to "cover your ass" rather than to be informative for developers and other stakeholders.
- People's experience suggests that others don't retain the information they read in a document.
- Documents are typically out of date (i.e. they are historical as soon as they are written).
- "I don't have time to read it" is a common reason why people don't read the architecture documentation.
- How large are people's architecture documents? (see results)
- As software architects, we aren't paid to write documentation, we're paid to build working software.
- Drawing on a whiteboard is often the best way to share an architecture.
- It's useful seeing how the diagram is drawn (i.e. where does it start, order of components, etc).
- It can be frustrating to re-draw the diagram(s) every time somebody asks about the architecture.
- Why isn't architecture documentation updated?
- UML diagrams are too much trouble (i.e. keeping them in sync with reality, use of a separate modelling tool, etc).
- Should CASE tools be better?
- Is it better to put the information in people's hands? (e.g. architecture information in the IDE).
If you came along, feel free to add your own notes in the comments. Both the slides and video are available for download, and stay tuned for a podcast of the audio from the session. The next user group is scheduled for Tuesday, 6th May.
About the author
Simon is an independent consultant specializing in software architecture, and the author of Software Architecture for Developers (a developer-friendly guide to software architecture, technical leadership and the balance with agility). He’s also the creator of the C4 software architecture model and the founder of Structurizr, which is a collection of open source and commercial tooling to help software teams visualise, document and explore their software architecture.
You can find Simon on Twitter at @simonbrown ... see simonbrown.je for information about his speaking schedule, videos from past conferences and software architecture training.