@DanLebrero.

software, simply

Book notes: Design It!: From Programmer to Software Architect

  • Wed, 4 May 2022

Book notes on "Design It!: From Programmer to Software Architect" by Michael Keeling

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):
    1. All design is social in nature: for and with people.
    2. Preserve ambiguity:
    3. All design is redesign.
    4. Make ideas tangible to facilitate communication.
  • Emphasize:
    1. Treat solutions as experiments.
    2. Focus on reducing risks.
    3. Work to simplify problems.
    4. Iterate quickly to learn quickly.
    5. Think about the problem and solution at the same time.
  • Use risk to decide what to focus on.
  • Architecturally Significant Requirements:
    1. Constraints:
      • Well-chosen constraints simplify the problem.
      • Early design decisions can become constraints in the future.
    2. Influential functional requirements:
      • Identifying influential functional requirements is equal part of art and science.
    3. Quality Attributes.
    4. 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?
    1. Define the problem from an engineering perspective.
    2. Partition the system and assign responsibilities.
    3. 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.
    4. Decide trade-offs among quality attributes.
    5. Manage technical debt.
    6. 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:
    1. Module: structure that exists at design time (class, DB table).
    2. Component and connector (C&C): exits at runtime (object, process).
    3. Allocations: how modules and C&C elements correspond to each other.
      • Aka: mapping structures.
  • 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):
    1. All design is social in nature:
      • For and with people.
    2. Preserve ambiguity:
    3. All design is redesign.
    4. Make ideas tangible to facilitate communication.
  • To design an architecture:
    1. Pick a mindset.
    2. Pick a practice within that mindset.
    3. Apply practice to learn something new.
    4. Goto (1).
  • Design mindsets:
    1. Understand:
      • Requires empathy.
    2. Explore.
    3. Make.
    4. Evaluate.

Part II - Architecture Design Fundamentals

Chapter 3 - Devise a Design Strategy

  • Emphasize:
    1. Treat solutions as experiments.
    2. Focus on reducing risks.
    3. Work to simplify problems.
    4. Iterate quickly to learn quickly.
    5. 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:
      1. Reduce probability.
      2. Reduce impact.
      3. Push out the time frame of the risk.
      4. Remove condition.
      5. 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:
    1. 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.
    2. Influential functional requirements (FR):
      • Identifying influential functional requirements is equal part of art and science.
      1. Sketch notional architecture.
      2. Identify classes of requirements:
        • Group FR with the same architecture elements (like persistence).
        • FR that seem difficult to implement.
        • High-value, high-priority FR.
      3. Try each class of requirements against the notional architecture:
        • If it is not obvious how to implement, the it might be an influential FR.
    3. Others:
      • Tech trends.
      • Architecture skills, knowledge.
      • Team skills, knowledge.
      • Team organization.
    4. 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:
      • Top scenarios.
    • 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:
    1. Architecture elements and their responsibilities.
    2. How elements interact with each other. Their interfaces.
    3. Understand the domain.
    4. Tech and framework that promote quality attributes.
    5. How app will be deployed.
    6. 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.
    1. Use architecture vocabulary.
    2. Organize code following architecture elements.
    3. Enforce relations, so that it becomes impossible to violate the architecture.
    4. 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:
    1. 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.
    2. Kick-off:
      • Share context.
    3. Create:
      • Choose design activity:
    4. Share:
      • 3-5 mins.
      • Only main points.
      • No questions or comments.
    5. Critique:
      • Specific.
      • Focus on facts.
      • Point also good things.
    6. Iterate:
      • Go to 3.
      • Tweak the group dynamics.
    7. 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:
    • Accurate, not precise.
  • 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?
    describe architecture
  • 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:
  • 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:
      1. Criteria:
        • ASR as a guide.
        • Important, essential, distinct, observable and measurable, precise and unambiguous.
      2. 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:
      1. Build templates for delegated work.
      2. Provide feedback during peer reviews.
      3. 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

  1. 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.
  2. Empathy Map:
    • Brainstorm and record responsibilities, thoughts and feelings for the team to develop empathy.
    • Updated version.
  3. Goal-Question-Metric Workshop:
    • Identify metrics and response measures to connect data with business goals.
      goal-question-metric
    • Question to answer to know if we have met the goal.
    • Result: prioritized data and metrics to gather.
  4. Interview Stakeholders:
    • Unstructured interviews should still have a checklist.
  5. List assumptions:
    • Take assumptions out of the shadows.
    • Write down everything mentioned, even obvious ones.
    • Pause to discuss surprising assumptions.
  6. Mini-Quality Attribute workshop:
    • Prepare:
      1. Quality attribute taxonomy (max 7).
      2. Quality attribute scenario templates.
      3. Quality attribute web.
      4. As homework, refine top raw quality scenarios. Present in a follow-up meeting.
  7. Point-of-View Mad Lib:
    • Summarize business goals and other needs.
    • Template:
      point of view mad lib
    • Consensus is not required.
    • Outcome focused.
  8. 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.
  9. 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

  1. 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.
  2. 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.
  3. Component responsibility collaborator cards:
    • Propose architectural elements, their responsibilities and how they come together to form a view of the architecture.
      crc card
  4. Concept map:
    • Visualize how concepts in the domain relate to one another.
    • Helps to uncover missing, hidden, or implied domain concepts.
  5. Divide and conquer:
    divide and conquer
    • Tight feedback loops work better.
  6. Event Storming:
    • Collaborative brainstorming technique used to identify domain events.
    • To better engage subject-matter experts.
    • Concrete and specific examples, not abstract.
  7. Group Posters:
    • Create a poster that conveys their design ideas for the architecture outcomes.
    • To summarize outcomes.
  8. Round-Robin design:
    • Quickly explore a range of ideas, and then combine to start building consensus.
    • Steps:
      1. Sketch 5m.
      2. Rotate.
      3. Critique 3m.
      4. Rotate.
      5. Improve 5m.
      6. Review all sketches.
  9. 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

  1. Architecture Decision Records:
    • Capture architecture design decisions using a lightweight text-based template.
  2. Architecture haiku:
    • Create bit-sized architecture summaries that stakeholders will actually use.
    • Think through and articulate the essential parts.
  3. Context diagram:
    • Help stakeholders understand where the software system fits in the world.
    • Agreement with system scope.
  4. Greatest hits reading list:
    • Help navigate the morass of design artifacts, so they can find relevant information.
    • Links list with tile, overview and caveats.
  5. 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.
  6. 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.
  7. Paths not taken:
    • List options discarded with a brief explanation of why.
  8. Prototype to learn or decide:
    • Always prototype as quickly and cheaply as possible.
  9. Sequential diagram.
  10. System metaphor.

Chapter 17 - Activities to Evaluate Design Options

  • Evaluation is a continuous activity.
  1. Architecture Briefing:
    • Brief presentation on some part of the architecture, to get meaningful feedback.
  2. Code review:
    • From architecture point of view.
  3. Decision Matrix:
    • Visual comparison of alternatives.
    • No more than 7 factors.
    • No more than 5 design options.
    • Take notes when filling the matrix.
  4. Observe Behaviour:
    • Add instrumentation to see runtime behaviours.
  5. 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.
  6. Risk storming:
    • Collaborative, visual technique for identifying risks in the architecture.
  7. Sanity check:
    • To expose issues in team communication or understanding.
    • Pop quiz-like.
  8. 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.
  9. 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.
Did you enjoy it? or share!

Tagged in : Architecture book notes