These are my notes on Design It!: From Programmer to Software Architect by Michael Keeling.
"From Programmer to Software Architect" is a spot on subtitle.
Key Insights
- SW design is a constant struggle to find the right balance between the things you want and the reality you must accept.
- Every team has at least one architect. The best teams have several.
- For every SW system you build, briefly describe the system and what you learned during your time developing it.
- Design Thinking Principles (From Design Thinking: Understand – Improve – Apply):
- All design is social in nature: for and with people.
- Preserve ambiguity:
- All design is redesign.
- Make ideas tangible to facilitate communication.
- Emphasize:
- Treat solutions as experiments.
- Focus on reducing risks.
- Work to simplify problems.
- Iterate quickly to learn quickly.
- Think about the problem and solution at the same time.
- Use risk to decide what to focus on.
- Architecturally Significant Requirements:
- Constraints:
- Well-chosen constraints simplify the problem.
- Early design decisions can become constraints in the future.
- Influential functional requirements:
- Identifying influential functional requirements is equal part of art and science.
- Quality Attributes.
- Others:
- Tech trends.
- Architecture skills, knowledge.
- Team skills, knowledge.
- Team organization.
- Our confidence in a decision increases after seeing multiple alternatives.
- Decision matrix: Do not use numbers as they give a false sense of confidence and precision.
- Complexity is an inevitable by-product of every successful software system.
- Discussion lacking in disagreement may seem like positive progress, but it is more likely to be the opposite.
- Sometimes a simple table is all that is needed.
- Precision gets in the way of communication: accurate, not precise.
- A good-looking document tells readers the content is trustworthy and was created by a professional.
- Sometimes your pile of rejected decisions can be more telling than a lengthy explanation.
- Keep design authority when risks of failure are high.
- The discussion is often more important than the option picked.
-
Empathy map.
-
The Agile Inception Deck.
All activities
Understand
Activity |
Time |
Participants |
Notes |
Choose one thing |
|
All stakeholders |
Clear prioritization and disagreement. |
Empathy map |
10-30m |
Solo or 3-5. Devs + Arch |
For the team to develop empathy. |
Goal-Question-Metric workshop |
15-90m |
1-5 people. |
Prioritized metrics to gather. |
Interview stakeholders |
30-60m per interview |
1-2-1 or small stakeholder group |
|
List assumptions |
15-30m |
Whole team in 2-5 groups |
Take assumptions out of the shadows. |
Mini-Quality attributes workshop |
90-180m |
Arch + 3-5 stakeholders |
|
Point-of-View mad lib |
30-45m |
1-3 people. Any stakeholder |
Summarize business goals and other needs. |
Response measure straw man |
Combine with other |
Architect prepares |
Get conversation moving. |
Stakeholder map |
30-45m |
1-25. Whole team + stakeholders |
Relations and interactions. |
Explore
Activity |
Time |
Participants |
Notes |
Personify the architecture |
|
|
It is ok to feel silly. |
Architecture flip book |
30-45m |
1-3 people |
Record all steps on design iteration. |
Component responsibility collaborator cards |
30-90m |
Solo or 3-5 |
Propose architectural elements. |
Concept map |
30-60m |
1-3 technical stakeholders |
Uncover missing domain concepts. |
Divide and conquer |
|
Groups of 2-4 |
To cover a lot of ground in parallel. |
Event Storming |
90m |
2-12. Expert + dev team |
Identify domain events. |
Group Posters |
20-30m |
Groups 2-5 people |
To summarize outcomes. |
Round-Robin design |
15-45m |
3-12 tech stakeholders |
Combine ideas + build consensus. |
Whiteboard Jam |
Up to the group |
3-5 tech stakeholders |
|
Make
Activity |
Notes |
Architecture Decision Records |
|
Architecture haiku |
One-page uber-terse summary |
Context diagram |
Agreement with system scope |
Greatest hits reading list |
|
Inception deck |
10 important questions at the start of a new project |
Modular decomposition diagram |
Tree diagram that shows relationships at different granularities |
Paths not taken |
|
Prototype to learn or decide |
|
Sequential diagram |
|
System metaphor |
|
Evaluate
Activity |
Time |
Participants |
Notes |
Architecture Briefing |
45-60m preparation. 30m present. 30m questions |
Arch + wide audience |
|
Code review |
Ongoing |
2 to whole team |
|
Decision Matrix |
Varies |
Arch + Stakeholders |
|
Observer Behaviour |
|
|
Observability in production |
Question-Comment-Concern |
30-90m |
Whole team |
|
Risk storming |
60-90m |
3-7 devs |
|
Sanity Check |
5-10m |
Whole team |
Pop quiz |
Scenario walk-through |
20-30m per quality attribute |
3-7 people |
Use early |
Sketch and Compare |
20-30m |
3-5 people |
|
TOC
Part I - Introducing Software Architecture
Chapter 1 - Become a Software Architect
- What architects do?
- Define the problem from an engineering perspective.
- Partition the system and assign responsibilities.
- Keep an eye on the bigger picture:
- System as a whole.
- SW design is a constant struggle to find the right balance between the things you want and the reality you must accept.
- Decide trade-offs among quality attributes.
- Manage technical debt.
- Grow the team's architecture skills:
- Architecture design is a social activity.
- A system's software architecture is the set of significant design decisions about how the software is organized to promote desired quality attributes and other properties.
- Software structure's elements and relations:
- Module: structure that exists at design time (class, DB table).
- Component and connector (C&C): exits at runtime (object, process).
- Allocations: how modules and C&C elements correspond to each other.
- Quality attribute is any externally visible characteristic by which stakeholders judge a SW system's goodness.
- Every team has at least one architect. The best teams have several.
- For every SW system you build, briefly describe the system and what you learned during your time developing it.
Chapter 2 - Design Thinking Fundamentals
- Design thinking: problem-solving approach that puts humans at the center.
- Principles (From Design Thinking: Understand – Improve – Apply):
- All design is social in nature:
- Preserve ambiguity:
- All design is redesign.
- Make ideas tangible to facilitate communication.
- To design an architecture:
- Pick a mindset.
- Pick a practice within that mindset.
- Apply practice to learn something new.
- Goto (1).
- Design mindsets:
- Understand:
- Explore.
- Make.
- Evaluate.
Part II - Architecture Design Fundamentals
Chapter 3 - Devise a Design Strategy
- Emphasize:
- Treat solutions as experiments.
- Focus on reducing risks.
- Work to simplify problems.
- Iterate quickly to learn quickly.
- Think about the problem and solution at the same time.
- How much design up front:
- Barry Boehm, Architecting: how much and when. Chapter 10 of Making Software.
- Total project time == dev time + architecture + rework.
- Architecture reduces rework time.
- Bigger systems benefit the most from more up-front architecture work.
-
COSYSMO and COCOMO II.
-
Use risk to decide what to focus on:
- [conditions] might [consequences]
- Deal with risk:
- Reduce probability.
- Reduce impact.
- Push out the time frame of the risk.
- Remove condition.
- Accept it and do nothing.
- Which mindset:
- Understand: risk is about problem.
- Explore: risk is about solution.
- Have you seen enough solution alternatives?
- Make: risk is about communication.
- Do stakeholders fully understand design and architecture?
- Evaluate: risk involves a design decision or the design's overall fit.
- Do we need to make a design decision?
- Create a design plan.
Chapter 4 - Empathize with Stakeholders
- Create a stakeholder map with stakeholders, stakeholders groups and their relationship.
- Record business goal statements:
- Subject, outcome, context.
- Outcome: measurable.
- Context: insightful and not obvious.
- Most systems only have three to five business goals.
Chapter 5 - Dig for Architecturally Significant Requirements (ASR)
- 4 Categories:
- Constraints:
- Unchangeable. Non-negotiable.
- Well-chosen constraints simplify the problem.
- Technical: programming lang, platforms, components, technology.
- Business: team structure, schedule, budget, legal.
- Early design decisions can become constraints in the future.
- Keep a XLS: constraint, origin, type, context.
- Influential functional requirements (FR):
- Identifying influential functional requirements is equal part of art and science.
- Sketch notional architecture.
- Identify classes of requirements:
- Group FR with the same architecture elements (like persistence).
- FR that seem difficult to implement.
- High-value, high-priority FR.
- Try each class of requirements against the notional architecture:
- If it is not obvious how to implement, the it might be an influential FR.
- Others:
- Tech trends.
- Architecture skills, knowledge.
- Team skills, knowledge.
- Team organization.
- Quality Attributes:
- Use quality attribute scenarios:
- Parts:
- Stimulus: event that triggers the scenario.
- Source: who.
- Artifact: part of the system.
- Response: externally visible action by the artifact as result of the stimulus.
- Response measure (Success criteria, Specific and measurable).
- Environment context: "normal", peak load, failure condition.
- Keep in XLS:
Quality Attribute |
Scenario |
Priority |
Availability |
When DB does not respond, respond with stale data within 3 secs |
high |
... |
... |
... |
- Build an architect significant requirements doc:
- Purpose and scope.
- Intended audience.
- Business context.
- Quality attribute requirements:
- Influential FR:
- Top users or user persona.
- Use cases or user stories.
- Appendix A: Glossary.
- Appendix B: Quality Attributes Taxonomy.
Chapter 6 - Choose an Architecture (Before It Chooses You)
- Our confidence in a decision increases after seeing multiple alternatives.
- You need to explore:
- Architecture elements and their responsibilities.
- How elements interact with each other. Their interfaces.
- Understand the domain.
- Tech and framework that promote quality attributes.
- How app will be deployed.
- Look at past designs.
- Decision matrix:
- I personally like text + color (red, white, green).
- Do not use numbers as they give a false sense of confidence and precision.
|
Option A |
Option B |
Option C |
Property 1 |
promotes |
+ |
|
Property 2 |
inhibits |
- |
|
Property 3 |
neutral |
o |
|
- Create an element responsibility catalog:
- Assign to each element the influential functional requirement.
Chapter 7 - Create a Foundation with Patterns
Chapter 8 - Manage Complexity with Meaningful Models
- Complexity is an inevitable by-product of every successful software system.
- Abstractions help us focus on specific details at the expense of others.
- Good architecture models:
- Establish the vocabulary of design.
- Direct attention to interesting details.
- Allows to reason about quality attributes.
- Captures the architect's intention.
- Design a meta-model: concepts and rules to use those concepts.
- Building models into the code:
- It is possible to shrink the model-code gap, but it cannot be closed completely.
- Use architecture vocabulary.
- Organize code following architecture elements.
- Enforce relations, so that it becomes impossible to violate the architecture.
- Add comments.
Chapter 9 - Host an Architecture Design Studio
- Design studio encourages group collaboration and has strict time constraints to help the team see a broad range of ideas in a short time frame.
- Creates buy-in of everybody involved.
- Outcomes:
- Things to make.
- Things to research more.
- New open questions.
- Typically, few hours to a day.
- Steps:
- Prepare:
- Business and workshop goals.
- Quality attributes.
- ASRs.
- Choose participants:
- 3-10.
- Diverse background.
- Discussion lacking in disagreement may seem like positive progress, but it is more likely to be the opposite.
- Kick-off:
- Create:
- Share:
- 3-5 mins.
- Only main points.
- No questions or comments.
- Critique:
- Specific.
- Focus on facts.
- Point also good things.
- Iterate:
- Go to 3.
- Tweak the group dynamics.
- Close:
- Reflect.
- Decide specific actions.
- Use a parking lot to record interesting ideas for other time, and keep the workshop moving.
Chapter 10 - Visualize Design Decisions
- Sometimes a simple table is all that is needed.
- Sometimes precision gets in the way of communication:
- Tips:
- Always include a legend.
- Add a descriptive title.
- Highlight patterns.
- Be consistent.
- Provide descriptive prose, and/or text annotations.
Chapter 11 - Describe the Architecture
- Which architecture description approach should I use?
- Tribal:
- Oral tradition, informal sketching, story telling.
- Communal:
- When you find yourself telling the same story to more than a few people.
- Architecture Haiku, ADR, architecturally evident coding style.
- Formal:
- High-risk systems or architecture decisions.
- Traditional SW architecture decision (SAD).
- Templates:
- Always keep the audience in mind:
- A good-looking document tells readers the content is trustworthy and was created by a professional.
- Establish viewpoints:
- Arch from the point of view of a related set of stakeholder concerns.
- Example standard viewpoints:
- Usually organized around quality attributes or stakeholder needs.
- Explain rationale:
- Sometimes your pile of rejected decisions can be more telling than a lengthy explanation.
Chapter 12 - Give the Architecture a Report Card
- Benefits of evaluation:
- Educate team.
- Create buy-in.
- Reduce delivery risks.
- Improve architecture.
- Design Rubric:
- 2 parts:
- Criteria:
- ASR as a guide.
- Important, essential, distinct, observable and measurable, precise and unambiguous.
- Rating:
- Select scale:
- 1-2: all or nothing. Few reviewers.
- 1-3: minimum acceptable threshold. Multiple reviewers.
- 1-4: Detailed feedback desired.
- Discuss any "1" score, even if the average is acceptable.
- Organize an architecture evaluation workshop:
- Steps: prepare, prime reviewers, assess, analyze, follow-up.
- It is important to understand why the design is fit (or not).
- Great designs can always be improved.
- Gold standard:
- Evaluate early, often, continuously:
- Risks.
- Unknowns.
- Problems.
- Gaps.
- Arch erosion.
- Contextual drift.
- Start with low ceremony methods.
Chapter 13 - Empower the Architects of Your Team
- Modern SW dev teams need a different kind of leader than the traditional top-down architect.
- Coach, mentor, technical guru.
- Teams who embrace the idea of SW architect as a way of thinking instead of as a role, produce better SW:
- More eyes.
- Team buy-in. Ownership.
- Create opportunities for safe practice:
- Pair design.
- Create scaffolding:
- Build templates for delegated work.
- Provide feedback during peer reviews.
- Create checklists.
- Introduce architectural guide rails:
- Guide rails (constraints) decreases the chances to mess up the architecture.
- Host information sessions.
- Keep design authority when risks of failure are high.
Part III - The Architect's Toolbox
Chapter 14 - Activities to Understand the Problem
- Choose One Thing:
- Discuss priorities by presenting an extreme choice.
- If you only get one thing, what will it be?
- Clear prioritization.
- Clear disagreement.
- The discussion is often more important than the option picked.
- Use early.
- Empathy Map:
- Brainstorm and record responsibilities, thoughts and feelings for the team to develop empathy.
-
Updated version.
- Goal-Question-Metric Workshop:
- Identify metrics and response measures to connect data with business goals.
- Question to answer to know if we have met the goal.
- Result: prioritized data and metrics to gather.
- Interview Stakeholders:
- Unstructured interviews should still have a checklist.
- List assumptions:
- Take assumptions out of the shadows.
- Write down everything mentioned, even obvious ones.
- Pause to discuss surprising assumptions.
- Mini-Quality Attribute workshop:
- Prepare:
- Quality attribute taxonomy (max 7).
- Quality attribute scenario templates.
- Quality attribute web.
- As homework, refine top raw quality scenarios. Present in a follow-up meeting.
- Point-of-View Mad Lib:
- Summarize business goals and other needs.
- Template:
- Consensus is not required.
- Outcome focused.
- Response Measure Straw Man:
- Give stakeholders something to beat up until they arrive at their own answers.
- Response either:
- Honest: if you are confident.
- Outrageous: to find boundaries.
- Stakeholder Map:
- To visualize relationships, hierarchies and interactions between people involved or impacted by the system.
- Once completed ask who are the most important stakeholders.
Chapter 15 - Activities to Explore Potential Solutions
- Personify the architecture:
- Give it human qualities so that you can explore interactions among elements.
- How it "reacts" or "feel", make it memorable through story telling.
- It is ok to feel a little silly.
- Architecture flip book:
- Record every step of the design journey so others can follow along afterwards.
- Sketch + notes about incremental changes.
- Teach others how to think about design and modeling.
- On a slide deck, keep copying the last slide and editing it.
- Component responsibility collaborator cards:
- Propose architectural elements, their responsibilities and how they come together to form a view of the architecture.
- Concept map:
- Visualize how concepts in the domain relate to one another.
- Helps to uncover missing, hidden, or implied domain concepts.
- Divide and conquer:
- Tight feedback loops work better.
- Event Storming:
- Collaborative brainstorming technique used to identify domain events.
- To better engage subject-matter experts.
- Concrete and specific examples, not abstract.
- Group Posters:
- Create a poster that conveys their design ideas for the architecture outcomes.
- To summarize outcomes.
- Round-Robin design:
- Quickly explore a range of ideas, and then combine to start building consensus.
- Steps:
- Sketch 5m.
- Rotate.
- Critique 3m.
- Rotate.
- Improve 5m.
- Review all sketches.
- Whiteboard Jam:
- Collaboratively draw diagrams on a whiteboard.
- Pictures won't make sense to someone who wasn't there.
Chapter 16 - Activities to Make the Design Tangible
- Architecture Decision Records:
- Capture architecture design decisions using a lightweight text-based template.
- Architecture haiku:
- Create bit-sized architecture summaries that stakeholders will actually use.
- Think through and articulate the essential parts.
- Context diagram:
- Help stakeholders understand where the software system fits in the world.
- Agreement with system scope.
- Greatest hits reading list:
- Help navigate the morass of design artifacts, so they can find relevant information.
- Links list with tile, overview and caveats.
- Inception deck:
- Answer 10 important questions at the start of a new project to avoid common failures and align stakeholders.
- The Agile Inception Deck
- Customize questions to your context.
- Effort to create should be proportional to size and cost of project.
- Modular decomposition diagram:
- Simple tree diagram that shows how abstractions at different granularities are related.
- Root is the whole system.
- Child are more and more specific.
- Paths not taken:
- List options discarded with a brief explanation of why.
- Prototype to learn or decide:
- Always prototype as quickly and cheaply as possible.
- Sequential diagram.
- System metaphor.
Chapter 17 - Activities to Evaluate Design Options
- Evaluation is a continuous activity.
- Architecture Briefing:
- Brief presentation on some part of the architecture, to get meaningful feedback.
- Code review:
- From architecture point of view.
- Decision Matrix:
- Visual comparison of alternatives.
- No more than 7 factors.
- No more than 5 design options.
- Take notes when filling the matrix.
- Observe Behaviour:
- Add instrumentation to see runtime behaviours.
- Question-Comment-Concern:
- Collaborative, visual activity to shine light on knowledge gaps, articulate issues, and establish known facts about the architecture.
- Team puts sticky notes (comments, questions, concerns) on views of the architecture.
- Risk storming:
- Collaborative, visual technique for identifying risks in the architecture.
- Sanity check:
- To expose issues in team communication or understanding.
- Pop quiz-like.
- Scenario walk-through:
- Describe step-by-step how the architecture addresses a specific quality attribute scenario.
- Use early.
- Avoid problem-solving during the session.
- Architect + note taker + session moderator + few reviewers. 3-7 total.
- Sketch and Compare:
- Create two or more alternatives of the same design, so it is easier to see the pros/cons.
- Always summarize the findings.
Top comments (0)