Handbook of Software Engineering Methods

🧭 Overview

🧠 One-sentence thesis

The SDLC defines five stages that all software projects must traverse—requirements, design, implementation, testing, and maintenance—but different process models like Agile and Waterfall move through these stages in fundamentally different patterns, with Agile's iterative approach showing significantly lower failure rates than Waterfall's sequential approach.

📌 Key points (3–5)

• The five SDLC stages: requirements, design, implementation, testing, and maintenance form the universal progression of software projects.
• Process models determine movement: Agile cycles through stages in short, frequent iterations with incremental releases; Waterfall moves linearly and sequentially with heavy documentation.
• Common confusion: Waterfall's sequential nature means you can't easily return to previous stages (like swimming up a waterfall), while Agile allows overlapping stages and planning for the next cycle during the current one.
• Failure rates differ dramatically: Agile projects fail 9% of the time versus 29% for Waterfall; the gap widens with project size (23% vs 42% for large projects).
• Why it matters: understanding process models helps you identify what your team is doing, choose appropriate methods for new projects, and rescue troubled projects.

🔄 The Five SDLC Stages

📋 Requirements

Figuring out and writing down what the software must do, how well, and under what limitations or constraints.

• This is the "what" stage—defining the software's purpose and boundaries.
• Not about how to build it, but what needs to be built.
• Includes performance criteria ("how well") and constraints (limitations).

🎨 Design

Determining how the software's code will be structured and how users will interact with the software.

• Covers two aspects: internal code structure and external user interaction.
• Translates requirements into architectural decisions.
• Bridges the gap between "what" (requirements) and "doing" (implementation).

💻 Implementation

Using the requirements and design to code the software.

• The actual coding stage.
• Depends on the previous two stages for guidance.

✅ Testing

Checking that the code was written without fault (verification) and that the software is what the users or client wants (validation).

• Two distinct purposes:
  • Verification: did we build it correctly? (no faults)
  • Validation: did we build the right thing? (matches user/client needs)
• Don't confuse: verification checks technical correctness; validation checks alignment with actual needs.

🔧 Maintenance

Improving software's existing functionality and code.

• Happens after initial release.
• Focuses on enhancement and refinement of what already exists.

🌊 Waterfall vs Agile Movement Patterns

🌊 Waterfall's sequential flow

• Movement is "fairly linear and sequential."
• Each stage depends on the previous stage being completed.
• Produces "lots of documentation."
• The name comes from the one-way flow: you can't swim up a waterfall, meaning returning to previous stages is difficult or not allowed.

Historical note: The excerpt mentions that Royce's 1970 article—often associated with Waterfall—actually depicted its major flaws and suggested modifications like preliminary program design and allowing returns to requirements as needed.

When it might make sense: The excerpt poses the question "Waterfall might not make sense for many software projects, but how about for building a bridge?"—suggesting physical construction projects may suit sequential approaches better.

🔄 Agile's iterative cycles

• Development cycles are "relatively short and numerous."
• Releases are "frequent and incremental."
• Each cycle adds "a little more working functionality."
• Planning (requirements and design) for the next cycle starts during the previous cycle—stages overlap.

Aspect	Waterfall	Agile
Cycle length	Long, single pass	Short, numerous cycles
Stage progression	Sequential, one-way	Overlapping, iterative
Releases	Infrequent, complete	Frequent, incremental
Documentation	Heavy	(Not specified, but implied lighter)
Return to earlier stages	Difficult/not allowed	Built into the process

🔀 How stages overlap in Agile

The excerpt provides a visual description: "The vertical lines represent development cycle boundaries. Planning (R,D) for the next development cycle starts during the previous cycle."

• Requirements (R) and Design (D) for cycle N+1 begin while cycle N is still in Implementation (I), Testing (T), or Maintenance (M).
• This overlap enables continuous progress and adaptation.

📊 Why Process Models Matter

📉 Failure rate data

The 2015 CHAOS report analyzed over 25,000 software projects:

Project type	Agile failure rate	Waterfall failure rate
Overall	9%	29%
Large projects	23%	42%
Small projects	4%	11%

Key insight: Agile shows lower failure rates across all project sizes, with the advantage most pronounced in large projects (19 percentage point difference).

Pattern: Project failure likelihood "increasing drastically with project size" for both models, but Waterfall suffers more.

🎯 Three practical reasons to understand process models

🔍 Detect and understand team practices

• When you're new to a team, understanding different models helps you "ask good questions."
• You can "identify what you see the team doing."
• Helps you "look competent in front of your team and managers."

🆕 Choose methods for new projects

• You might need to "select a software process model or method for a new project."
• You might need to "choose or recommend how your team proceeds."
• Having knowledge of options enables informed decisions.

🚨 Rescue troubled projects

• 17% to 22% of software projects failed during fiscal years 2011 to 2015.
• "Sometimes, you can save a project if you have the right methods."
• Understanding alternatives gives you tools for course correction.

🔗 Agile Frameworks and Methods

🏉 Scrum

• Described as "an Agile framework."
• One specific way to implement Agile principles.
• The excerpt notes this chapter gives "the flavor of Agile and Scrum rather than being a comprehensive guide."

⚡ Extreme Programming (XP)

• Another way to "go about developing and managing software in an Agile way."
• Listed alongside Scrum as a notable Agile method.

📜 The Agile Manifesto

• Agile is "guided by the Agile Manifesto."
• The Manifesto begins: "We are uncovering better ways of developing software by doing it and helping others do it."
• Emphasizes "Individuals and interactions" (the excerpt cuts off mid-list).

Don't confuse: Agile is the overall philosophy/process model; Scrum and XP are specific frameworks/methods for implementing Agile principles.

🧭 Overview

🧠 One-sentence thesis

Agile is a philosophy emphasizing flexibility and collaboration, Scrum is a concrete framework that implements Agile values through structured roles and events, and Agile methods are specific practices teams use within these frameworks.

📌 Key points (3–5)

• Agile's core philosophy: values individuals/interactions, working software, customer collaboration, and responding to change over rigid processes and plans.
• Why organizations choose Agile: majority adoption (51% leaning toward Agile, 16% pure Agile) driven by enhanced collaboration, increased quality, customer satisfaction, faster time to market, and reduced costs.
• Scrum framework structure: organized into three categories—team (roles), events (meetings/cycles), and artifacts (work products).
• Common confusion—Agile vs Scrum vs methods: Agile is the philosophy with no concrete implementation; Scrum is one framework that gives concrete guidance; methods (like Scrum boards, spikes, user stories) are specific practices teams use.
• Flexibility through Sprints: Scrum breaks projects into short fixed-length cycles (typically 2–4 weeks) to enable responding to change, with plans defined shortly before each Sprint.

🎯 The Agile philosophy

💡 What Agile values

The Agile Manifesto (Beck et al., 2001) states four value pairs:

Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan

• The items on the right still have value, but Agile prioritizes the items on the left more.
• This is a philosophy, not a concrete process—there's not just one way to follow it.

📊 Why organizations adopt Agile

According to an HP survey of 601 respondents (Hewlett Packard Enterprise, 2017):

Adoption distribution:

• 51%: Leaning toward Agile
• 46%: Hybrid
• 16%: Pure Agile
• 7%: Leaning toward Waterfall
• 2%: Pure Waterfall

Benefits reported by 403 organizations using Agile:

Benefit	Percentage agreeing
Enhances collaboration between teams	54%
Increases software quality	52%
Increases customer satisfaction	49%
Shortens time to market	43%
Reduces development cost	42%

• Example: Most organizations use Agile for software or IT projects because it addresses multiple business goals simultaneously—quality, speed, cost, and collaboration.

🔄 Scrum framework structure

👥 The Team roles

The Scrum Team consists of three roles with distinct focuses:

Role	Accountability	Focus
Scrum Master	Establishing Scrum as defined in the Scrum Guide	Process
Product Owner	Maximizing the value of the product	Product (software)
Developers	Creating any aspect of a usable Increment each Sprint	Creating product while following Scrum

• Don't confuse: all three roles are part of one Scrum Team, but each has a different primary responsibility.
• The Scrum Master ensures the team follows Scrum correctly; the Product Owner ensures the right product gets built; Developers build it.

📅 The Events (meetings and cycles)

Scrum defines five events that structure the work:

The Sprint:

Fixed-length development periods of "one month or less"—a new Sprint starts immediately after the previous Sprint concludes.

• Typically two to four weeks long.
• Reflects the "responding to change" value: teams might only know what's happening for a couple weeks at a time.

Sprint Planning:

• Initiates the Sprint by laying out the work to be performed.
• Plans are defined shortly before the Sprint, not months in advance.

Daily Scrum:

• A 15-minute event for the Developers only.
• Focuses on progress toward the Sprint Goal and produces an actionable plan for the next day of work.

Sprint Review:

• Inspects the outcome of the Sprint and determines future adaptations.
• The Scrum Team presents results to key stakeholders.
• Example: team shows completed features to customers and decides what to adjust.

Sprint Retrospective:

• Plans ways to increase quality and effectiveness.
• The Scrum Team inspects how the last Sprint went.
• This is team-only (unlike Sprint Review which includes stakeholders).

📦 The Artifacts (work products)

Scrum defines three artifacts that represent work and value:

Product Backlog:

An emergent, ordered list of what is needed to improve the product.

• Contains a rough list of tasks the team is planning to do sometime.
• Tasks haven't yet been scheduled and may not be defined in detail.

Sprint Backlog:

Composed of the Sprint Goal (why), the set of Product Backlog items selected for the Sprint (what), and an actionable plan for delivering the Increment (how).

• Contains tasks the team has decided to work on.
• Has added details about completing the tasks.
• Don't confuse with Product Backlog: Sprint Backlog is more specific and scheduled; Product Backlog is broader and unscheduled.

Increment:

A concrete stepping stone toward the Product Goal.

• An achievement toward creating the product.
• Example: finishing a feature implementation.

🛠️ Agile methods (specific practices)

📋 Scrum board

A way to organize and visualize tasks or work as cards on a board, with columns for different categories.

• Each card is placed within a column representing its status.
• Can be physical (bulletin board with sticky notes or index cards) or digital (task management software feature).
• Example: columns might be "To Do," "In Progress," "Done"—cards move across as work progresses.

🔍 Spike

A quick and to-the-point investigation for gathering information to help the team answer a question or choose a development path.

• Used when the team needs to research something before committing to an approach.
• Example: a team might do a spike to evaluate two competing technologies before deciding which to use.

📝 User story

A short description of a software feature from the perspective of fulfilling a user need.

• Common format: "As a [role] I can [capability], so that [receive benefit]."
• Tasks, priorities, time/cost estimates, and acceptance criteria may be associated with a user story.
• Example: "As a customer I can reset my password, so that I can regain access to my account."

🔑 Distinguishing Agile, Scrum, and methods

🧩 How they relate

The excerpt emphasizes a hierarchy of abstraction:

Level	What it is	Concreteness
Agile	Philosophy with associated values	Abstract—no concrete meaning, not just one way to follow it
Scrum	Framework for software project management	More concrete—gives concrete guidance on development and project management
Agile methods	Specific practices (Scrum board, spike, user story)	Most concrete—can be used within Scrum or other frameworks

• Agile aligns with the Agile philosophy (e.g., Scrum's short Sprints reflect "responding to change").
• Scrum Teams fit their own methods into the Scrum framework.
• Methods can be used within Scrum, other frameworks, or other software process models.

📖 Scrum Guide as definition

• Scrum is defined by the current version of the Scrum Guide (Schwaber & Sutherland, 2020).
• The Scrum Guide is "ever-evolving" and "changes frequently."
• The guide describes framework elements in more detail and defines additional terms (e.g., Sprint Goal).

🧭 Overview

🧠 One-sentence thesis

Agile is a philosophy without one concrete implementation, while Scrum provides a specific framework with defined roles, events, and artifacts to guide software development and project management.

📌 Key points (3–5)

• What Agile is: a philosophy with associated values, not a single concrete method—there's no one way to follow it.
• What Scrum provides: concrete guidance through a framework defined by the Scrum Guide, which changes frequently.
• Common confusion: Agile vs. Scrum—Agile is the philosophy; Scrum is one framework that implements Agile principles.
• Scrum structure: three roles (Scrum Master, Product Owner, Developers), five events (Sprint, Sprint Planning, Daily Scrum, Sprint Review, Sprint Retrospective), and three artifacts (Product Backlog, Sprint Backlog, Increment).
• Agile methods: techniques like Scrum boards, spikes, and user stories can be used within Scrum or other frameworks.

🎯 Agile as philosophy vs. Scrum as framework

🎯 What Agile means

"Agile" has associated values but no concrete meaning: it's a philosophy, and there's not just one way to follow it.

• Agile is not a specific process or set of steps.
• It represents values and principles for software development.
• Multiple approaches can all be "Agile" as long as they align with the philosophy.

📋 What Scrum provides

Agile frameworks such as Scrum give more concrete guidance on software development and project management.

• Scrum translates Agile philosophy into specific practices.
• It is defined by the Scrum Guide (Schwaber & Sutherland, 2020).
• The Scrum Guide changes frequently, so the framework evolves over time.
• Don't confuse: Agile tells you why and what values to hold; Scrum tells you how to organize work.

👥 Scrum roles and their focus

👥 The three roles

The excerpt defines three distinct roles, each with a different focus:

Role	Focus	Responsibility
Scrum Master	Process	Ensuring the team follows Scrum and removing obstacles
Product Owner	Product (software)	Maximizing the value of the product resulting from the team's work
Developers	Creating a product while following Scrum processes	Committed to creating any aspect of a usable Increment each Sprint

🔍 How roles differ

• The Scrum Master cares about how the team works.
• The Product Owner cares about what gets built and its value.
• Developers care about building the product within the process.
• Example: If a team is stuck on a technical decision, the Scrum Master helps the process move forward, the Product Owner clarifies what outcome delivers value, and the Developers implement the solution.

📅 Scrum events: the rhythm of work

📅 The Sprint

The Sprint: fixed-length development periods of "one month or less . . . A new Sprint starts immediately after the conclusion of the previous Sprint."

• Sprints are the container for all other events.
• They have a fixed length (one month or less).
• There is no gap between Sprints—one ends, the next begins.

🗓️ Sprint Planning

Sprint Planning: "initiates the Sprint by laying out the work to be performed."

• Happens at the start of each Sprint.
• The team decides what work will be done during the Sprint.

⏰ Daily Scrum

Daily Scrum: "a 15-minute event for the Developers of the Scrum Team . . . focuses on progress toward the Sprint Goal and produces an actionable plan for the next day of work."

• A short, daily meeting (exactly 15 minutes).
• Only for Developers (not the whole team).
• Purpose: check progress and plan the next day.
• Don't confuse: This is not a status report to a manager; it's a planning session for the Developers themselves.

🔍 Sprint Review

Sprint Review: "to inspect the outcome of the Sprint and determine future adaptations. The Scrum Team presents the results of their work to key stakeholders . . ."

• Happens at the end of the Sprint.
• The team shows what they built to stakeholders (people outside the team).
• Purpose: inspect the outcome and decide what to do next.

🔄 Sprint Retrospective

Sprint Retrospective: "to plan ways to increase quality and effectiveness . . . Scrum Team inspects how the last Sprint went . . ."

• Also happens at the end of the Sprint.
• Only the Scrum Team (no stakeholders).
• Purpose: reflect on the process and plan improvements.
• Don't confuse: Sprint Review is about the product (with stakeholders); Sprint Retrospective is about the process (team only).

📦 Scrum artifacts: tracking what needs to be done

📦 Product Backlog

Product Backlog: "an emergent, ordered list of what is needed to improve the product."

• A rough, prioritized list of tasks the team might do someday.
• Tasks are not yet scheduled or detailed.
• It evolves over time ("emergent").

📋 Sprint Backlog

Sprint Backlog: "composed of the Sprint Goal (why), the set of Product Backlog items selected for the Sprint (what), as well as an actionable plan for delivering the Increment (how)."

• Contains tasks the team has committed to for the current Sprint.
• Includes three parts: why (Sprint Goal), what (selected items), how (actionable plan).
• More detailed than the Product Backlog because the team is actively working on these tasks.

✅ Increment

Increment: "a concrete stepping stone toward the Product Goal."

• A tangible achievement toward the final product.
• Example: finishing a feature implementation.
• Each Sprint should produce at least one Increment.

🔍 How artifacts relate

• Product Backlog = "We might do this someday."
• Sprint Backlog = "We will do this now, and here's how."
• Increment = "We finished this piece."

🛠️ Agile methods: techniques within Scrum

🛠️ Scrum board

A way to organize and visualize tasks or work as cards on a board. The board has columns for different categories, and each card is placed within a column.

• Can be physical (bulletin board with sticky notes) or digital (task management software).
• Helps the team see what work is in progress, what's done, and what's waiting.

🔬 Spike

A quick and to-the-point investigation for gathering information to help the team answer a question or choose a development path.

• Not a full feature or task.
• Purpose: research or exploration to reduce uncertainty.
• Example: A team might do a spike to test whether a new library will work for their needs before committing to use it.

📝 User story

A short description of a software feature from the perspective of fulfilling a user need (e.g., using this format: As a <role> I can <capability>, so that <receive benefit>).

• Focuses on the user's need, not technical details.
• May include tasks, priorities, time/cost estimates, and acceptance criteria.
• Example format: "As a [role] I can [capability], so that [receive benefit]."
• Don't confuse: A user story is not a technical specification; it describes what the user wants to accomplish, not how the system will be built.

🔗 How these methods fit together

• These methods (Scrum board, spike, user story) are not exclusive to Scrum.
• They can be used within Scrum, other Agile frameworks, or even other software process models.
• They provide practical tools to support Agile values and Scrum practices.

🧭 Overview

🧠 One-sentence thesis

Software engineers benefit from understanding project management because they may become managers, work with managers, or need to self-manage within their teams.

📌 Key points (3–5)

• Three reasons to learn: you might become a project manager, you might have one and need to understand their work, or you might need to self-manage in flat or Agile organizations.
• What project management is: the process of planning and executing a project while balancing time, cost, and scope constraints (the triple constraint).
• Core challenge: minimizing time and money while delivering adequate features requires managing risk.
• Common confusion: scope vs quality—in software engineering, quality is considered part of scope/requirements, not a separate constraint.
• Why it matters: these constraints are difficult to balance, and common challenges (scope creep, underestimation, resource conflicts) are so frequent you should assume they will happen and plan mitigation strategies in advance.

🎯 Who needs project management knowledge

👤 Three scenarios for software engineers

Software engineers encounter project management in multiple roles:

• Becoming a project manager: your employer may ask you to fill the role, or you may pursue a new position.
• Working with a project manager: understanding basics helps you comprehend what they're doing (e.g., using a RACI matrix to define team responsibilities) and what they're communicating about the project.
• Self-managing: necessary in organizations with flattened hierarchies or within Agile teams where traditional management structures are reduced.

Example: If your manager mentions "updating the RACI matrix," understanding project management helps you recognize they're clarifying who is responsible, accountable, consulted, or informed for each task.

🔄 Why this matters in Agile contexts

The excerpt notes this chapter is "geared toward Agile" environments, where self-management is more common. Traditional hierarchical management may not exist, making project management knowledge essential for individual contributors.

⚖️ The triple constraint

📐 Three interconnected limits

Triple constraint: the three constraints of time, cost, and scope that must be balanced in project management.

Constraint	What it covers
Time	Duration of the project, intermediate deadlines
Cost	Monetary resources, personnel, and other project resources
Scope	What the project is meant to accomplish and the requirements of the project, including quality

🔍 Scope includes quality

Don't confuse: In some fields, quality is treated as separate from scope. In software engineering, requirements include quality—quality is part of scope, not a fourth constraint.

🎯 The optimization problem

Project management: the process of planning and executing a project while balancing the time, cost, and scope constraints.

The core question: How can we use limited financial and personnel resources to complete our project by the deadline, without going over budget, while delivering adequate features?

🚨 Common challenges and risk management

⚠️ Predictable problems

The excerpt emphasizes these situations are so common you can assume they're going to happen:

• Scope creep: A client says, "Oh, I forgot to mention we want this feature. That won't be a big deal, right?"
• Hidden dependencies: You realize late in the project that to implement feature A, you'll need to implement B, C, and D as well.
• Planning fallacy: Your team's estimates were overly optimistic.

🛡️ Risk and mitigation

Risk: the estimated probability of a loss given a set of known and unknown factors.

• Risk can be stated as high, medium, low, or numerically.
• Ways to mitigate risk (from the excerpt):
  • Defining and keeping track of your project
  • Communicating with your project team
  • Researching the implications of decisions
  • Developing backup plans
  • Selecting suitable tools

🔗 Complex real-world tradeoffs

Beyond simple constraint balancing, the excerpt provides examples of how constraints interrelate and affect personal relationships:

Example 1: Friend collaboration

• Your friend is an excellent coder but only available for three months (time constraint).
• They have their own ideas about project direction (scope).
• Giving them more control means quicker implementation and less work for you (cost benefit).
• But you must sacrifice some of your own feature priorities (scope tradeoff).

Example 2: Team billing pressure

• A colleague needs help, but all hours must be billed to a project.
• You're pressured to stay close to budget, and you bill at a higher rate than your colleague (cost constraint).
• If the colleague doesn't get help, they might spend extra hours self-training (cost increase).
• They could switch to a different project (resource loss).
• There's a small chance they'll negatively impact the project (the excerpt cuts off here, but implies scope or time risk).

📋 Mitigation planning

The excerpt stresses developing a mitigation plan even before the project starts, recognizing that many situations are:

• More complicated (more factors with more interrelationships)
• More unique to your context
• Involving factors that leak from professional to personal life

🧭 Overview

🧠 One-sentence thesis

The triple constraint framework shows that project managers must balance time, cost, and scope, and adjusting one constraint requires corresponding changes in the others.

📌 Key points (3–5)

• What the triple constraint is: the three core constraints in project management—time (duration and deadlines), cost (money, personnel, and resources), and scope (what the project accomplishes, including quality requirements).
• The balancing challenge: reducing time or cost, or increasing scope, requires adjusting one or more other constraints; you cannot change one in isolation.
• Common real-world pressures: clients adding features mid-project, discovering hidden dependencies late, and overly optimistic estimates (planning fallacy) are so common you should assume they will happen.
• Common confusion: in software engineering, quality is part of scope (requirements), not a separate fourth constraint as in some other fields.
• Why it matters: understanding these trade-offs helps you make strategic project decisions and prepare mitigation plans before problems arise.

🎯 The three constraints

⏰ Time

Time: duration of the project, intermediate deadlines.

• Refers to the overall project timeline and any milestones along the way.
• Not just the final deadline—includes intermediate checkpoints.
• Example: A project with a three-month window and monthly sprint deadlines has time constraints at multiple levels.

💰 Cost

Cost: monetary, personnel, and other project resources.

• Includes direct money spent, but also human resources (team members' hours) and other project inputs.
• Personnel cost can vary by role—higher-rate team members cost more per hour.
• Example: If a senior engineer helps a junior colleague, the billable cost is higher than if the junior engineer works alone, even for the same number of hours.

📦 Scope

Scope: what the project is meant to accomplish and the requirements of the project, including quality.

• Defines what the project must deliver and the standards it must meet.
• In software engineering, quality is built into scope (part of requirements), unlike in some other fields where quality is treated separately.
• Example: A client requirement for "secure login with two-factor authentication" defines both a feature (what) and a quality standard (secure).

⚖️ Balancing the constraints

🔗 The interdependence principle

• The excerpt states: "If you want to reduce time and cost spent on a project or increase project scope, you'll need a corresponding change in one or more other constraints."
• You cannot optimize all three simultaneously—improving one typically requires trade-offs in another.
• This is the core optimization challenge: "How can we use our limited financial and personnel resources to complete our project by the deadline, without going over budget?"

🚧 When scope is fixed

• The excerpt notes: "Scope is fixed: the product must satisfy all its requirements."
• When requirements cannot be negotiated, time and cost become the only adjustable variables.
• This scenario is common in contracts or regulatory environments where deliverables are non-negotiable.

🔥 Common challenges and mitigation

🎲 Predictable problems

The excerpt identifies three challenges that are "so common that you can assume they're going to happen":

Challenge	What happens	Impact
Mid-project feature creep	Client says "I forgot to mention we want this feature. That won't be a big deal, right?"	Scope increases unexpectedly
Hidden dependencies	You realize late that implementing feature A requires implementing B, C, and D as well	Scope and time increase
Planning fallacy	Team's estimates were overly optimistic	Time and cost overruns

🛡️ Mitigation planning

• Because these situations are predictable, you should "assume they're going to happen and come up with a mitigation plan even before the project starts."
• Don't wait for problems to appear—build buffers and contingency plans upfront.

🧩 Real-world complexity

🤝 Interpersonal trade-offs

The excerpt provides a scenario involving a friend who is an excellent coder:

• Time constraint: Friend only available for three months.
• Scope tension: Friend has their own feature priorities.
• Cost benefit: Friend's enthusiasm means quicker implementation and less work for you.
• Scope sacrifice: Giving the friend more control means sacrificing some of your own feature priorities.
• This illustrates how constraints interact with team dynamics and personal relationships.

💼 Team resource allocation

The excerpt describes a five-person team scenario:

• Cost pressure: All hours must be billed to the project; you're pressured to stay close to budget; you bill at a higher rate than your colleague.
• Cost vs. time trade-off: If the colleague doesn't get help, they might spend extra hours self-training (cost), could switch projects, or make the project take longer (time).
• Fixed scope: The product must still satisfy all requirements regardless of these pressures.
• This shows how professional constraints can "leak from your professional life to your personal life" and involve "more factors with more interrelationships."

🔍 Don't confuse

• Simple vs. complicated situations: The excerpt distinguishes between the three predictable challenges (which can be planned for) and "more complicated" situations with "more factors," "more interrelationships," and factors "more unique to your context."
• Not all constraint problems have straightforward solutions—some require navigating human factors, organizational politics, and personal relationships.

🧭 Overview

🧠 One-sentence thesis

Effective project management requires balancing three broad skill categories—interpersonal, technical, and administrative/conceptual—with the specific mix varying by management level.

📌 Key points (3–5)

• The three skill categories: interpersonal (communication), technical (methods and tools), and administrative/conceptual (big-picture vision and execution).
• Mix varies by level: high-level managers (e.g., CEOs) need a different skill balance than lower-level managers (e.g., project managers).
• Project manager focus: project managers typically need strong interpersonal and technical skills, with less emphasis on big-picture conceptual work.
• Common confusion: all managers need all three skills, but the proportions differ—don't assume every manager role requires equal amounts of each.
• Why it matters: understanding the required skill mix helps managers prioritize development and allocate responsibilities appropriately.

🎯 The three skill categories

🗣️ Interpersonal skills

Interpersonal: Communicating effectively with anyone likely to affect the project (e.g., engineers on your team, managers, clients, contractors, IT support, etc.).

• This is about communication effectiveness across all stakeholders, not just your immediate team.
• The excerpt emphasizes breadth: you must communicate with many different types of people who can influence the project.
• Example: An organization's project manager needs to communicate with their own engineers, upper management, external clients, third-party contractors, and internal support staff.

🔧 Technical skills

Technical: Using methods and equipment effectively (e.g., knowledge of appropriate processes, understanding and writing code, etc.).

• Covers both methods (processes, workflows) and equipment (tools, code).
• Not just knowing what exists, but using them effectively.
• Example: A project manager might need to understand code well enough to review it, or know which development processes fit the project's needs.

🏢 Administrative and conceptual skills

Administrative and conceptual: Understanding the "big picture" vision (conceptual) and being able to move macro-level pieces (e.g., teams, departments, divisions, etc.) toward that vision (administrative).

• Two related components:
  • Conceptual: grasping the overall organizational vision
  • Administrative: moving large organizational units (teams, departments, divisions) toward that vision
• This is about macro-level coordination, not day-to-day task management.
• Example: An organization's leader understands where the company should be in five years (conceptual) and reorganizes departments to move toward that goal (administrative).

📊 How the mix changes by management level

📊 Different roles, different proportions

Management level	Typical skill emphasis	What the excerpt says
High-level (e.g., CEOs)	More administrative/conceptual	"tend to need a different mix of skills than lower-level managers"
Lower-level (e.g., project managers)	More interpersonal + technical	"might need strong interpersonal and technical skills while only occasionally considering the big picture"

• The excerpt explicitly contrasts CEOs with project managers to illustrate the difference.
• Don't confuse: this is not about whether a skill is needed, but how much emphasis it receives.

🎯 Project manager emphasis

• Project managers need strong interpersonal and technical skills.
• They occasionally consider the big picture of how their project fits into the organization's overall vision.
• This chapter focuses on interpersonal and technical skills because it is about project management specifically.
• Example: A project manager spends most time communicating with the team and understanding technical implementation, and less time thinking about company-wide strategic direction.

🔗 Context: the triple constraint

⚖️ Three project constraints

The excerpt mentions the managerial skill mix in the context of balancing project constraints:

• Time: duration and deadlines

• Cost: monetary, personnel, and other resources

• Scope: what the project accomplishes, including requirements and quality

• The excerpt notes that "making strategic project decisions involves adjusting project constraints."

• The skill mix helps managers navigate these trade-offs: interpersonal skills for stakeholder negotiation, technical skills for understanding feasibility, and conceptual skills for aligning with organizational priorities.

🧩 Why skill mix matters for constraints

• The excerpt does not explicitly connect skill mix to constraint management, but places them in sequence.
• Implied relationship: different skills help address different constraint challenges.
  • Interpersonal: negotiating scope changes with clients or team members
  • Technical: accurately estimating time and cost based on implementation knowledge
  • Administrative/conceptual: deciding which projects align with organizational vision

🧭 Overview

🧠 One-sentence thesis

Improving team communication through structured methods—ground rules, role clarity, and consensus-building—reduces project risk and increases the likelihood of project success.

📌 Key points (3–5)

• Core claim: Better team communication reduces risk and increases project success probability.
• Team development context: Teams progress through forming, storming, norming, performing, and adjourning stages; communication methods fit differently at each stage.
• Three main methods: Ground rules prevent/resolve conflict, RACI matrices clarify who does what, and fist of five builds consensus.
• Common confusion: Ground rules must feel meaningful and authentic to the team—if they seem silly, phony, or too rigid, they can invalidate the team's efforts.
• Risk reduction mechanism: These methods reduce risk by preventing misunderstandings, clarifying responsibilities, surfacing problems early, and increasing team motivation.

🌱 Team development stages

🌱 Tuckman's model

The excerpt provides Tuckman's model as background context for understanding when and how communication methods apply:

Stage	What happens
Forming	Members test boundaries, establish dependency relationships with peers/leaders/standards
Storming	Members resist group influence, peers, peers' ideas, and tasks
Norming	Team develops cohesiveness, devises new standards/roles, members express personal opinions about tasks
Performing	Roles become flexible; team dynamics and structure serve the function of the team and task performance
Adjourning	Team disbands

🔄 How methods fit stages

• The excerpt notes there's "not just one answer" for where each communication method fits.
• Communication methods can be applied at different stages depending on team needs.
• Example: Ground rules might exist when a team forms (forming stage), develop as the team normalizes (norming stage), or be revised as work proceeds (performing stage).

📜 Ground rules for conflict prevention

📜 What ground rules are

Ground rules: a preemptive or reactive method for reducing team conflict and dysfunction.

• Ground rules can exist before team formation, develop during normalization, or be revised as the team identifies new concerns or opportunities.
• Critical requirement: The whole team must buy in for ground rules to be effective.
• Teams may incorporate existing standards (e.g., IEEE Code of Ethics, Agile Manifesto).

❓ Questions to define ground rules

The excerpt provides seven categories of questions teams should consider:

1. Vision: What is this team or what are we trying to accomplish together?

   • Example: "Clients choose us because we're honest and transparent."

2. Priorities: What do we prioritize most?

   • Example: "Delivering a high-quality product ahead of the deadline, input from all team members, honoring diverse end-users."

3. Day-to-day communication: What methods will we use?

   • Example: "No interrupting, no 'splaining, listen to and acknowledge what other people are saying, ask people if they're busy before starting a long conversation."

4. Conflict communication: How will we communicate during conflict?

   • Example: "We'll use nonviolent communication, we'll focus on solving the problem instead of who to blame."

5. Work habits: What expectations do we have?

   • Example: "Tuesdays from 1:00 to 3:00 p.m. is silent time; be five minutes early to meetings."

6. Responsiveness: What expectations do we have?

   • Example: "Respond within two hours during regular work hours; have the team Discord open during regular work hours."

7. Failure handling: What will we do when members fail expectations?

   • Example: "We'll discuss any team problems on Fridays at 3:00 p.m."

⚠️ Authenticity requirement

Don't confuse: Ground rules that look good on paper vs. ground rules that work.

• Questions and answers vary by individuals and context (e.g., culture).
• Ground rules should feel meaningful and authentic.
• Warning signs that invalidate ground rules:
  • Team feels they are silly
  • Team feels they are phony
  • Too aspirational (unrealistic)
  • Too inflexible (can't adapt)
  • Too authoritative (imposed from above)

📋 End product

• A list of short statements posted where people will see it regularly.
• The visibility ensures ongoing awareness and reinforcement.

🎯 RACI matrix for role clarity

🎯 What a RACI matrix is

RACI matrix: a chart for defining who is responsible (R) and accountable (A) for a task or deliverable, and who should be consulted (C) or informed (I).

• Can be formatted as a table or written as a list.
• Organizes tasks or deliverables into phases.
• One person might have multiple roles for the same task.

🔤 The four RACI roles

Letter	Role	Meaning
R	Responsible	Who will do the work
A	Accountable	Who will approve the work and make sure it gets done
C	Consulted	Who can discuss and offer advice about the work
I	Informed	Whom to keep up to date about the status of the work

📊 Example structure

The excerpt provides a detailed example for a Minimum Viable Product (MVP) phase with multiple sub-tasks:

• Focus groups: Frontend Lead is both R and A; Team Lead is both R and A; developers are C (consulted).
• Requirements specification: Developers and designers are R (responsible); leads are A (accountable) and I (informed).
• Throwaway code design: Backend developers are R; Backend Lead is A; other leads are I.
• Implementation: Developers are R; leads are A; Team Lead is C and I.
• User acceptance testing: Frontend developers and designers are R; Frontend Lead is R and A.

🛡️ Risk reduction through RACI

How it reduces risk:

• Prevents "not knowing who needs to do what."
• Prevents forgetting assignments.
• Prevents plausible deniability (people claiming they didn't know).
• Negative event prevented: Shipping a broken product because nobody was assigned to quality assurance.

The excerpt emphasizes that unclear responsibilities increase the probability of negative events and outcomes.

✋ Fist of five for consensus

✋ What fist of five is

Fist of five: a method for checking and building consensus within a group of people.

Process:

1. One person (e.g., team leader) makes a statement or proposes an idea.
2. Each person holds up a fist or up to five fingers to show their level of agreement or support.
3. Associated with Agile but also used by students of different ages.

🌍 Cultural context warning

The excerpt includes an important cultural note:

• Single-finger hand gestures vary around the world.
• Example: Thumb up means "good job" in the United States, "one" in Germany and Hungary, "five" in Japan, and "up yours!" in Australia, Greece, and the Middle East.
• Teams must be aware of cultural differences when using hand-gesture methods.

🔢 What each number means

Fingers	Meaning	Action
None (fist)	Strong reject	Blocks consensus
One	Reject	Major issues need resolving now
Two	Weak reject	Minor issues need resolving now
Three	Weak accept	Minor issues can be resolved later
Four	Accept	No issues
Five	Strong accept	Willing to lead or champion

🔄 Iterative consensus process

When rejection occurs (two or fewer fingers):

1. Team stops.
2. Team discusses.
3. Team makes changes.
4. Team votes again.
5. Repeat until there's sufficient consensus.

Flexibility: It's up to the team or its leader to decide how much consensus is needed.

🛡️ Risk reduction through fist of five

Two ways it reduces risk:

1. Bringing problems to light: Makes disagreements and concerns visible immediately.
2. Increasing team motivation, ownership, and investment: When people have a voice in decisions, they become more committed.

Example: If someone holds up one finger (reject with major issues), the team learns about a serious problem before moving forward, preventing later failures.

🧭 Overview

🧠 One-sentence thesis

Project definition methods—including scope statements, constraint balancing, task prioritization, estimation, scheduling, and management systems—help teams organize work and reduce project risk by making priorities, dependencies, and timelines explicit.

📌 Key points (3–5)

• Scope varies by methodology: Agile projects define scope flexibly through task sets and iteration goals, while other environments use formal scope documents stating objectives, deliverables, and requirements.
• Balancing constraints: The project priority matrix helps teams decide which constraint (time, cost, scope) to fix, improve, or allow to worsen.
• Prioritization layers: Use the Eisenhower matrix for high-level sorting (urgent/important), then apply finer methods like asking experts, spikes, dependency analysis, or customer input.
• Common confusion: Story points vs ideal days—story points measure relative size compared to other tasks; ideal days measure absolute time assuming no distractions.
• Why it matters: These methods surface unknowns, dependencies, and priorities early, which mitigates risk and prevents resource waste.

📋 Defining Project Scope

📋 What scope means in different contexts

Project scope (a.k.a. statement of work): a document stating the project's objective, deliverables (outputs), milestones, technical requirements, and limitations/exclusions.

In Agile environments:

• Scope is implied through task sets: release plan, Product Backlog, iteration plan, Sprint Backlog.
• Each iteration may have a goal (e.g., Sprint Goal) summarizing what the tasks accomplish.
• Scope is purposely flexible and emerges as the project proceeds.

In other environments:

• Scope is a specific document.
• It explicitly lists what will and won't be done.

🔍 Why scope definition matters

• Clarifies what the team is committing to deliver.
• Helps avoid scope creep (uncontrolled expansion).
• In Agile, flexibility allows adaptation; in traditional projects, the document provides a fixed reference.

⚖️ Balancing Constraints

⚖️ The project priority matrix

Project priority matrix: a tool for stating the desired balance among time, scope, and cost by assigning each constraint one of three priorities: constrain, enhance, or accept.

What each priority means:

• Constrain: the constraint is fixed (can get better but must not get worse).
• Enhance: try to improve (e.g., take less time, spend less, have more features).
• Accept: can worsen (e.g., more time, more personnel, fewer features) if necessary.

Example scenario: You have a grant to develop medical device software that regulates pain levels.

Constraint	Priority	Reasoning
Scope	Constrain	Must deliver what was promised; partial functionality would be a disaster when testing on human subjects
Cost	Constrain	Grant is fixed amount funded by taxpayers; must control spending tightly
Time	Accept	If needed, can submit intermediate results and seek another grant

🛡️ How the matrix reduces risk

• Defined before the project starts (with the client).
• Referenced throughout the project as needed.
• Helps the team or project manager balance constraints in ways acceptable to the client.
• Prevents misunderstandings about which trade-offs are acceptable.

🎯 Task Prioritization

🎯 High-level: Eisenhower matrix

Eisenhower matrix: a method for sorting tasks by urgency and importance into four categories: Do, Decide, Delegate, Delete.

	Urgent	Not Urgent
Important	Do (correctly and now)	Decide (correctly but not immediately)
Not Important	Delegate (now, but mistakes tolerable)	Delete (eliminate)

Examples for each cell:

• Do: Documenting undocumented code so a new hire can start contributing.
• Decide: Refactoring currently working code—needs to be done right eventually; maybe the new hire can handle it in a couple months.
• Delegate: Initializing the task management system so the team can begin defining tasks; if not done right, developers and managers will adjust; good learning task for the new hire.
• Delete: Implementing a loading screen that looks like a game of pong, but you're the only one who thinks it's cool.

🔍 Why the Eisenhower matrix matters

• Conserves resources by eliminating low-value tasks.
• Uses resources thoughtfully (including yourself).
• Helps escape "putting out fires" mode (concentrating only on urgent tasks), which can leave important but non-urgent tasks eternally at the end of the to-do list, potentially causing project failure.

🔬 Finer-grained prioritization methods

When multiple important tasks have the same urgency, use:

Ask an expert (for implementation tasks):

• Experts know from experience which tasks have more unknowns, risk, dependencies, etc.

Do a spike (if you're meant to be an expert):

Spike: a focused research effort to gather more information about a task, which helps prioritize it.

Steps to do a spike:

1. Come up with a question.
2. Try to figure out the answer by reading (documentation, opinions) and experimenting (e.g., coding in a sandbox).
3. Repeat until you have enough information.

A good way: start doing the task and see what obstacles you run into.

Example: You need to set up a local server for testing and then write a test suite. You have experience writing test suites but have never set up a server. After doing a spike, you realize some tests rely on the server having a static IP address (not the default). You decide to prioritize server setup because (1) the test suite depends on it and (2) the server setup still has many unknowns and uncertain duration.

Think about dependencies:

• Who's waiting on you to complete the task?
• How many other tasks depend on this task?

Example: You estimate 15 minutes to complete a task that two people are waiting on. You do that before your four-hour task. Seems obvious—but if you're unaware of dependencies or deep in solo work mode, you might make a suboptimal choice.

Ask the customer or users (for feature selection):

• Directly: phone call, focus group, survey.
• Indirectly: support tickets, marketing team input, detecting unmet needs from how people use other software.

Other feature selection methods:

• Voting (within your team).
• Pairwise comparison (Is Feature A more valuable than Feature B? Is Feature C more valuable than Feature A?).

🛡️ How prioritization reduces risk

A natural side effect of prioritization is discovering:

• How long tasks take.
• What dependencies exist.
• Who the players are.
• What the end user wants.

All this knowledge contributes to risk mitigation.

📏 Estimation

📏 Two methods for stating task size

1. Story points:

Story points: a number assigned to a task representing its size relative to other tasks.

• Example: A software installation and a virus scan might both be a 1 if they take roughly the same time and effort, have roughly the same risk, etc.
• Implementing a major feature might be an 8.
• Your team decides how far the scale goes.
• Common scales: 1 to 10, Fibonacci, powers of 2.
• Fibonacci and powers of 2 put more distance between numbers, making sizing easier; deciding between 4 and 8 can be easier than between 4 and 5.

2. Ideal days:

Ideal days: the number of days you think it would take to complete the task if there were no other tasks or distractions.

• Example: If it takes 5 minutes to remove one square foot of grass and you have 100 square feet to remove, that's 8 hours 20 minutes total, so about one ideal day (if workdays are 8 or 9 hours).

🔍 Don't confuse story points and ideal days

• Story points are relative: "This task is twice as big as that one."
• Ideal days are absolute: "This task would take 3 days with no interruptions."

🚀 Velocity

Velocity: work completed (in story points or ideal days) by an Agile team.

• Teams can make statements like "This month, we will complete 50 story points" or "10 ideal days."
• Teams make initial velocity estimates and adjust based on accuracy.

🃏 Planning poker: how estimates are assigned

Planning poker: an Agile method where the team discusses tasks and each person privately estimates, then reveals and discusses differences.

Process:

1. Each person gets a set of cards with possible story points, ideal days, or other aspects.
2. One person describes the task.
3. The team asks questions as needed.
4. Each person privately decides on an estimate by selecting a card (keeping it face down or hidden).
5. Once everyone is ready, cards are revealed.
6. Variations in estimates are expected and part of the process: differences open discussion.
   • High estimate: may identify reasons why a task is likely to take a long time.
   • Low estimate: may identify an efficient idea nobody else thought of.
7. The team discusses and can repeat until estimates become sufficiently consistent.

📅 Scheduling

📅 Project network diagram

Project network diagram: a directed graph showing a project's tasks, the sequence in which they should be completed, and the dependency relationships between the tasks.

Structure:

• Nodes represent tasks.
• Lines with arrows represent dependency or sequence relationships.
• Moves left to right, where left is earlier in time.
• This format is called Activity-on-Node (AON).

🔧 Requirements for a task to be on the diagram

• Must be distinct from other tasks.
• Its dependent tasks (a.k.a. predecessors) must be known.
• More useful if estimates for the tasks are also known.

🛠️ Constructing a project network diagram

Manual or automatic:

• Can be created manually.
• Can be automatically generated by software (e.g., MS Project, Lucidchart).

For automatic generation: Enter project data in tabular form (e.g., spreadsheet).

Example table:

Task ID	Task	Predecessors	Duration (hours)
1	Select GUI framework		2
2	Prototype GUI		8
3	Test GUI with users	2	5
4	Implement GUI	1,3	50

Note: Even though Task 2 must happen before Task 4, it's not listed as a predecessor because it's not an immediate predecessor.

Additional options: Depending on software, you might have access to more complex options like specific dates by which individual tasks must be completed.

🗂️ Task Management Systems

🗂️ What they are and why they're useful

Task management system: software used to organize tasks, task details (description, acceptance criteria, assignee, status), and other relevant information (e.g., which iteration or phase the task belongs to).

Benefits:

• Organizing and storing information about tasks.
• Satisfaction of marking a task as done.
• Strongly oriented toward team collaboration (e.g., Asana, Jira, Trello).
• Some are Agile-oriented, offering Agile-inspired features (e.g., templates).

⚙️ Common features

• Create, remove, update, and delete tasks.
• Enter task name, description, notes/comments, and add attachments.
• View tasks as a list, as cards on a board, or within a timeline (e.g., Gantt chart).
• Organize tasks into projects.
• Assign tasks to different team members, with due dates.
• Enter task status (e.g., in progress, done).
• Get email notifications about tasks.
• Add tags, keywords, and categories.

🔍 Limitations and alternatives

Project network diagrams:

• Task management systems don't have a universal way to generate project network diagrams.
• For that, you might need a fully featured project management system (e.g., MS Project).
• But you may find that a Gantt chart or road map feature meets your needs and is available within your task management system.

🧭 Overview

🧠 One-sentence thesis

Effective project management combines communication methods, task-definition techniques, and visualization tools to reduce project failure risk and enable teams to complete larger projects while balancing time, scope, and cost.

📌 Key points (3–5)

• The triple constraint: project management requires balancing time, scope, and cost.
• Communication tools: ground rules, RACI matrices for roles/responsibilities, and fist-of-five consensus building improve team coordination.
• Task definition methods: priority matrices, story points, ideal days, and planning poker help teams estimate and prioritize work.
• Visualization techniques: project network diagrams and task management systems organize dependencies and track progress.
• Common confusion: immediate predecessors vs all predecessors—only direct dependencies need to be listed in project network diagrams.

🗣️ Team communication methods

📋 Ground rules

• Establishing ground rules helps teams coordinate and set expectations.
• These rules guide how the team will work together.

👥 RACI matrix

• A tool for defining roles and responsibilities across the team.
• Clarifies who is responsible, accountable, consulted, and informed for each task.

✋ Fist of five method

• A technique for measuring and building consensus within the team.
• Helps teams make decisions collaboratively.

📊 Defining and prioritizing tasks

🎯 Priority matrices

• Project priority matrix: helps prioritize tasks based on project goals.
• Eisenhower matrix: another prioritization framework for organizing work.
• Both tools help teams decide which tasks to tackle first.

📏 Estimation techniques

Story points: a unit for estimating task effort or complexity.

• Ideal days: another estimation approach measuring work in ideal time units.
• Planning poker: a collaborative estimation method where team members estimate together.
• These methods help teams predict how long work will take without relying solely on clock time.

🗺️ Visualizing project structure

🔗 Project network diagrams

Project network diagram: a directed graph showing a project's tasks, their sequence, and dependency relationships between tasks.

• Nodes represent tasks; arrows show dependencies and sequence.
• Moves left to right, where left is earlier in time.
• Also called Activity-on-Node (AON) format.

Requirements for tasks to appear on the diagram:

• Must be distinct from other tasks.
• Dependent tasks (predecessors) must be known.
• More useful when task estimates are also available.

📝 Creating the diagram

• Can be created manually or automatically generated by software (e.g., MS Project, Lucidchart).
• Requires entering project data in tabular form with: Task ID, Task name, Predecessors, Duration.

Don't confuse: Only immediate predecessors need to be listed. If Task 2 must happen before Task 4, but Task 3 comes between them, only Task 3 needs to be listed as Task 4's predecessor.

Example: A table might show Task 4 depends on Tasks 1 and 3, with Task 2 as an indirect dependency not listed.

🛠️ Task management systems

💻 What they provide

Task management system: software used to organize tasks, task details (description, acceptance criteria, assignee, status), and other relevant information.

Common features:

• Create, remove, update, and delete tasks.
• Enter task details: name, description, notes, comments, attachments.
• Multiple view options: list, cards on a board, or timeline (e.g., Gantt chart).
• Organize tasks into projects.
• Assign tasks to team members with due dates.
• Track task status (e.g., in progress, done).
• Email notifications, tags, keywords, and categories.

🔄 Team collaboration focus

• Systems like Asana, Jira, and Trello emphasize team collaboration.
• Some offer Agile-inspired features and templates.
• Provide satisfaction of marking tasks as done.

⚖️ Limitations

• Don't universally generate project network diagrams.
• For full network diagrams, may need a complete project management system (e.g., MS Project).
• Gantt charts or road map features may meet needs within task management systems.

🎯 The triple constraint

Element	Role in project management
Time	One of three factors that must be balanced
Scope	What the project will deliver
Cost	Resources and budget available

• Good project management requires balancing all three elements.
• Changes to one element typically affect the others.

🧭 Overview

🧠 One-sentence thesis

Software requirements fall into two main types—functional (what the software must do) and nonfunctional (how well it must do it or what constraints it must respect)—and both are essential for guiding design, implementation, and project success.

📌 Key points (3–5)

• Two main types: functional requirements describe behaviors under specific conditions; nonfunctional requirements describe properties, characteristics, or constraints.
• Why requirements matter: they prevent developers from prioritizing personal preferences, keep teams synchronized, protect against stakeholder drift, and facilitate communication.
• Quality standards: good requirements should be correct, unambiguous, complete, consistent, verifiable, and traceable.
• Common confusion: don't confuse functional (what the system does) with nonfunctional (how well it does it or what limits it must respect)—both are needed.
• Elicitation methods: requirements come from stakeholders through interviews, focus groups, lab studies, and exploratory research.

🔍 The two main requirement types

🔍 Functional requirements

Functional requirements: "A description of a behavior that a system will exhibit under specific conditions."

• They answer the question: "What must the software do?"
• Focus on actions and behaviors triggered by specific conditions.
• Example: "If the user activates the 'log in' button, the login page will appear."
• This is about the system's response to user input or conditions, not about speed or quality.

🔍 Nonfunctional requirements

Nonfunctional requirements: "A description of a property or characteristic that a system must exhibit or a constraint that it must respect."

• They describe how well the system performs or what limits it must work within.
• Two subcategories:
  • Quality attributes (characteristics the system must exhibit): e.g., responsiveness—"the login page will appear within 500 milliseconds."
  • Constraints (limits the system must respect): e.g., "The GUI toolkit must be able to display non-rectangular windows."
• Don't confuse: nonfunctional requirements are not about what the system does, but about performance, quality, or boundaries.

🖼️ Visual example

The excerpt provides a concrete illustration:

• A rolling table that fails a nonfunctional requirement (doesn't fit through an average door—a constraint).
• The same table fails a functional requirement (doesn't have four legs—a behavior/feature).

🎯 Why requirements matter

🎯 Preventing developer drift

• Without requirements, developers might prioritize functionality they personally find important or fun.
• What developers want to implement might not align with project success.

🎯 Keeping teams synchronized

• When multiple developers work on the same code, requirements help them stay in sync and pursue the same goal.
• Without requirements, time, effort, and money can be wasted implementing conflicting code.

🎯 Protecting against stakeholder influence

• Stakeholders include clients, partners, investors, consultants, and management.
• Without specified requirements, stakeholders can influence the project toward satisfying their own (possibly fleeting) wants or needs.
• This can cause the project to drift away from its original intent and lead to failure.

🎯 Facilitating communication and decision-making

• Requirements help communicate about software with stakeholders.
• They help keep track of everything that needs to get done.
• They help you and the client decide what really needs to get done (clients sometimes don't know what they really need).

✅ Standards for good requirements

✅ Core quality criteria

Good requirements should be:

Criterion	What it means
Correct	What they say is right
Unambiguous	Only one way to interpret them
Complete	Cover all that's important
Consistent	Not contradictory
Ranked	Ordered by importance and/or stability
Verifiable/testable	There's a way to figure out if they're satisfied
Modifiable	They can be changed
Traceable	Possible to figure out where they came from

✅ Additional organizational standards

Requirements should also be:

• Cross-referenced to earlier documents that relate.
• Uniquely identifiable (each requirement can be distinguished).
• Organized for maximum readability.

Note: Teams or organizations can choose their own standards; this is one set of standards.

🗣️ Requirements elicitation

🗣️ What elicitation means

Requirements elicitation: the process of gathering requirements.

• Requirements can come from any stakeholder: clients, managers, users, governments, developers of software to be integrated with yours, the development team, and yourself.
• Elicitation involves both:
  • Detecting stakeholders' wants and needs.
  • Using your professional judgment to decide which requirements to focus on.

🗣️ Methods for detecting wants and needs

The core approach: communicate and observe.

Method	Description
Interviews	Structured (questions defined ahead), semi-structured (some predefined, some generated during interview), or unstructured conversations
Focus groups	Small group conversations where participants discuss topics among themselves with moderator guidance
Lab studies	Participants perform tasks in a controlled setting (e.g., try an early prototype, then give feedback)
Exploratory research	Multiple methods of immersing oneself in the world of relevant people and products to gain knowledge and develop empathy for stakeholders

Example of exploratory research: After doing a fly-on-the-wall observation, you realize people can't find Aisle 25 because it's in an unexpected place. You decide to prioritize the Aisle Map feature in the store's app.

🗣️ Who performs elicitation

• Depending on the software development environment, these methods might be the jurisdiction of specialist researchers in marketing or interaction design.
• Developers can also elicit requirements (the excerpt notes this but does not elaborate further).

🧭 Overview

🧠 One-sentence thesis

Requirements guide software development by aligning developers' work with project goals, preventing wasted effort, and enabling effective communication with stakeholders.

📌 Key points (3–5)

• Why requirements prevent misdirection: Without requirements, developers may prioritize what they find interesting rather than what makes the project successful.
• How requirements enable coordination: Multiple developers can stay synchronized and pursue the same goal instead of implementing conflicting code.
• What requirements protect against: Stakeholder influence that can cause project drift away from original intentions, potentially leading to failure.
• Common confusion: Requirements are not just for tracking tasks—they also help decide what really needs to get done, since clients sometimes don't know what they truly need.
• Communication value: Requirements facilitate dialogue with stakeholders and help manage scope.

🎯 Preventing developer-driven drift

🎯 The personal priority problem

• Without requirements, developers might prioritize functionality they personally think is important or fun to implement.
• The excerpt emphasizes that what developers want to implement might not make the project successful.
• This is a mismatch between developer interest and project success criteria.

Example: A developer might spend time building an elegant algorithm they find intellectually interesting, but the project may actually need a simple, reliable data entry form.

🔄 Don't confuse with technical decisions

• This is about what to build, not how to build it.
• Requirements guide feature selection, not just implementation choices.

🤝 Enabling team coordination

🤝 Synchronization across developers

• When multiple developers work on the same code, requirements help them stay in sync and pursue the same goal.
• Without requirements, time, effort, and money can be wasted implementing conflicting code.

Example: Developer A builds a login system expecting user data in one format, while Developer B builds a registration system producing data in a different format—requirements would have specified the shared data structure.

⚠️ The cost of misalignment

• The excerpt explicitly mentions three resources at risk: time, effort, and money.
• Conflicting code means rework, integration problems, and wasted resources.

🛡️ Protecting against stakeholder drift

🛡️ Who stakeholders are

The excerpt defines stakeholders as:

• Clients
• Partners
• Investors
• Consultants
• Management

🌊 The drift problem

• When requirements aren't specified, it's easier for stakeholders to influence the project toward satisfying their own (possibly fleeting) wants or needs.
• This can result in the project drifting away from what it was originally intended to do.
• The excerpt warns this can lead to project failure.

🔄 Fleeting vs. foundational needs

• The excerpt specifically notes stakeholder wants may be "possibly fleeting"—temporary or changing preferences.
• Without requirements as an anchor, the project can chase moving targets.

💬 Facilitating communication and decision-making

💬 Multiple communication functions

Requirements are helpful for:

• Communicating about software with stakeholders
• Keeping track of everything that needs to get done
• Helping you and the client decide what really needs to get done

🧩 The hidden knowledge problem

"clients sometimes don't know what they really need"

• This is a key insight: requirements are not just about capturing stated wants.
• The process helps surface and clarify actual needs versus perceived wants.
• Requirements serve as a tool for collaborative discovery, not just documentation.

Example: A client might request a feature-rich dashboard with dozens of metrics, but through requirements discussion, you discover they really need three key indicators displayed clearly—the complexity would actually hinder their work.

📋 Tracking vs. deciding

Function	What it means
Keeping track	Managing the list of tasks and features
Deciding what needs to get done	Prioritizing and determining necessity

• These are distinct activities—requirements support both inventory and judgment.

🧭 Overview

🧠 One-sentence thesis

Good requirements follow specific standards—such as being correct, unambiguous, complete, consistent, verifiable, and traceable—that help teams build software that meets stakeholder needs without wasting effort or drifting from the original goal.

📌 Key points (3–5)

• Two types of requirements: functional (what the software must do) vs. nonfunctional (how well it must perform or what constraints it must respect).
• Why requirements matter: they prevent developers from prioritizing personal preferences, keep teams synchronized, protect projects from stakeholder drift, and help communicate what really needs to be done.
• Standards for good requirements: correct, unambiguous, complete, consistent, ranked, verifiable, modifiable, traceable, cross-referenced, uniquely identifiable, and organized for readability.
• Common confusion: nonfunctional requirements are not vague—they should include measurable quantities (e.g., "within 500 milliseconds") to make them testable.
• Requirements elicitation challenges: stakeholders may lack expertise, have bad ideas, not know what they want, want harmful things, or communicate imperfectly—developers must use professional judgment.

🔍 Functional vs. Nonfunctional Requirements

🔍 Functional requirements

"A description of a behavior that a system will exhibit under specific conditions."

• They answer: "What must the software do?"
• Example: "If the user activates the 'log in' button, the login page will appear."
• Focus is on behavior and actions the system performs.

⚙️ Nonfunctional requirements

"A description of a property or characteristic that a system must exhibit or a constraint that it must respect."

• They answer: "How well must the software do it?" or "What limits must it respect?"
• Example (characteristic): "If the user activates the 'log in' button, the login page will appear within 500 milliseconds."
  • This adds a quality attribute: responsiveness.
• Example (constraint): "The GUI toolkit must be able to display non-rectangular windows."
• Don't confuse: nonfunctional requirements are not optional or vague—they describe measurable performance or hard constraints.

🖼️ Illustration of failed requirements

The excerpt provides a visual example:

• A rolling table that fails the nonfunctional requirement of fitting through an average door.
• The same table fails the functional requirement of having four legs.

🎯 Why Requirements Matter

🎯 Preventing wasted effort and drift

• Without requirements, developers might prioritize what they personally find important or fun, not what makes the project successful.
• Multiple developers working without requirements can implement conflicting code, wasting time, effort, and money.

🛡️ Protecting against stakeholder influence

• Stakeholders (clients, partners, investors, consultants, management) can push the project toward their own fleeting wants or needs if requirements aren't specified.
• This can cause the project to drift away from its original purpose and lead to failure.

💬 Communication and decision-making

• Requirements help communicate about software with stakeholders.
• They help keep track of everything that needs to get done.
• They help you and the client decide what really needs to get done—clients sometimes don't know what they really need.

📋 Standards for Good Requirements

📋 Core quality criteria

Criterion	What it means
Correct	What they say is right
Unambiguous	There is only one way to interpret them
Complete	They cover all that's important
Consistent	They aren't contradictory
Ranked	For importance and/or stability
Verifiable/testable	There's a way to figure out if they're satisfied
Modifiable	They can be changed
Traceable	It's possible to figure out where they came from

📋 Additional organizational standards

• Cross-referenced to earlier documents that relate.
• Uniquely identifiable.
• Organized for maximum readability.

🧪 Why verifiability matters

• A requirement must be testable—there must be a way to determine whether it has been satisfied.
• Example: "Response time should be a few seconds or less" is testable; "The system should be fast" is not.
• Nonfunctional requirements should include quantities to make them verifiable (e.g., "within 500 milliseconds," "99.99% uptime").

🗣️ Requirements Elicitation

🗣️ What elicitation is

Requirements elicitation: the process of gathering requirements.

• Requirements can come from any stakeholder: clients, managers, users, governments, developers of integrated software, the development team, and yourself.
• Elicitation involves both detecting stakeholders' wants and needs and using professional judgment to decide which requirements to focus on.

🔬 Methods for detecting wants and needs

Method	Description
Interviews	Structured (questions defined ahead), semi-structured (some predefined, some generated during), or unstructured conversations
Focus groups	Small group conversations where participants discuss topics among themselves with moderator guidance
Lab studies	Participants perform tasks in a controlled setting (e.g., try an early prototype, then give feedback)
Exploratory research	Multiple methods of immersing oneself in the world of relevant people and products to gain knowledge and empathy

• Example of exploratory research: After a fly-on-the-wall observation, you realize people can't find Aisle 25 because it's in an unexpected place, so you prioritize the Aisle Map feature in the store's app.
• Note: In some environments, these methods are the jurisdiction of specialist researchers in marketing or interaction design.

⚠️ Challenges when developers elicit requirements

• Stakeholders might not have experience or expertise: Developers can help bridge the gap between what stakeholders want and what is technically feasible and reasonable (given time, cost, and scope—the triple constraint).
• Stakeholders might not have good ideas: They might be incorrect about what they or others want or will use. Methods like focus groups, usability testing, and releasing a minimum viable product (MVP) can help figure out whether users will actually use (and pay for) the software.
• Stakeholders might not know what they want: They may have a rough idea or an idea that conflicts with their actual wants or needs.
• Stakeholders might want what's bad for them or others: Example—users want apps that make their face beautiful in photos, but such features may promote unrealistic beauty standards.
• Stakeholders are humans: They communicate imperfectly.

🧠 Developer judgment

• With experience, you can learn how to effectively gather relevant information from stakeholders and make your own judgments about how that information translates into requirements.

📏 Nonfunctional Requirements in Detail

📏 What they describe

• Nonfunctional requirements describe how well the software needs to perform or what constraints it must respect.

📏 Examples with quantities

• "Response time should be a few seconds or less in all operating environments."
• "The front-end design must be evaluated using the Inclusivity Heuristics by at least two people each Sprint."
• "The software must be available 24 hours a day, seven days a week, and must have an uptime of 99.99%."

📏 Why quantities matter

• Each nonfunctional requirement should have a quantity to make it testable (a criterion for a good requirement).
• Without a measurable target, it's impossible to verify whether the requirement has been met.

🏷️ Quality attributes

Quality attributes: words for describing "a service or performance characteristic of software."

• The excerpt mentions a long list exists on Wikipedia's "List of system quality attributes" page.
• One common quality attribute mentioned: Maintainability (amount of effort required to maintain the software).
• Quality attributes are the characteristics that nonfunctional requirements specify (e.g., responsiveness, availability, maintainability).

🧭 Overview

🧠 One-sentence thesis

Requirements elicitation is the process of gathering requirements from all stakeholders through communication and observation, while using professional judgment to decide which requirements to prioritize despite the inherent challenges of human communication and stakeholder limitations.

📌 Key points (3–5)

• What elicitation involves: both detecting stakeholders' wants and needs through various methods, and applying professional judgment to decide what to focus on.
• Who provides requirements: any stakeholder—clients, managers, users, governments, integrated software developers, the development team, and yourself.
• Methods for detecting needs: interviews (structured/semi-structured/unstructured), focus groups, lab studies, and exploratory research.
• Common confusion: stakeholders may not know what they want, may lack expertise, or may want things that are bad for them or others—developers must bridge these gaps rather than simply implement every request.
• Human communication challenges: stakeholders communicate imperfectly, may have bad ideas, or may be incorrect about what they or others will actually use.

🎯 What requirements elicitation is

🎯 Definition and dual nature

Requirements elicitation: the process of gathering requirements.

• It is not just collecting what stakeholders say they want.
• It involves two components:
  1. Detecting stakeholders' wants and needs
  2. Using professional judgment to decide which requirements to focus on
• Requirements can come from any stakeholder: clients, managers, users, governments, developers of software to be integrated with yours, the development team, and yourself.

🔍 Why judgment matters

• The excerpt emphasizes that elicitation is not passive collection—you must decide what to prioritize.
• Example: After fly-on-the-wall observation, you realize people can't find Aisle 25 because it's in an unexpected place, so you decide to prioritize the Aisle Map feature in the store's app.

🛠️ Methods for detecting wants and needs

💬 Interview approaches

The excerpt describes three types:

Type	Description
Structured	Questions defined ahead of time
Semi-structured	Some questions predefined, some generated during interview
Unstructured	Conversations without predetermined questions

👥 Focus groups

• Small group conversations where participants discuss topics among themselves.
• A moderator provides guidance.
• Allows stakeholders to interact and build on each other's ideas.

🧪 Lab studies

• Participants perform tasks in a controlled setting.
• Example: try to use an early prototype, then give feedback.
• Provides direct observation of user behavior.

🔬 Exploratory research

Exploratory research: multiple methods of immersing oneself within the world of relevant people and products, with the purpose of gaining knowledge and developing empathy for stakeholders.

• Involves immersion in the stakeholders' world.
• Purpose: gain knowledge and develop empathy.
• Example method mentioned: fly-on-the-wall observation.
• Example outcome: realizing Aisle 25 is hard to find leads to prioritizing an Aisle Map feature.

🎨 Specialist methods

• Depending on the software development environment, these methods might be the jurisdiction of specialist researchers in marketing or interaction design.
• The excerpt references Hanington and Martin (2019) for more detailed descriptions of specialist methods.

⚠️ Challenges when developers elicit requirements

🎓 Lack of experience or expertise

• Challenge: Stakeholders might not have experience or expertise.
• Developer role: Help bridge the gap between what the stakeholder wants and what is technically feasible and reasonable.
• Constraint context: Given time, cost, and scope (also known as the triple constraint).
• Don't confuse: "what stakeholders want" with "what is feasible"—developers must translate between these.

💡 Bad or incorrect ideas

• Challenge: Stakeholders might not have good ideas; they might be incorrect about what they or other people want or will use.
• Developer role: Can sometimes provide guidance toward better ideas.
• Important caveat: Developers can also have bad ideas.
• Solution methods: Focus groups, usability testing, and releasing a minimum viable product (MVP) can help figure out whether users will use (and pay for) the software.

❓ Uncertainty about wants

• Challenge: Stakeholders might not know what they want.
• They may have:
  • A rough idea only
  • An idea that's at odds with their actual wants or needs
• This is distinct from having bad ideas—they may simply be unclear or conflicted.

🚫 Wanting harmful things

• Challenge: Stakeholders might want what's bad for them or others.
• Example from excerpt: Users want apps that make their face beautiful in photos; such features may promote unrealistic beauty standards.
• Developers face ethical decisions about which requirements to implement.

🗣️ Imperfect communication

• Challenge: Stakeholders are humans; they communicate imperfectly.
• This is a fundamental limitation that cannot be eliminated.
• With experience, you can learn how to effectively gather relevant information from stakeholders and make your own judgments about how that information translates into requirements.

🧠 Learning to elicit effectively

📈 Experience-based skill

• The excerpt emphasizes that effective elicitation improves with experience.
• Two key learned skills:
  1. How to effectively gather relevant information from stakeholders
  2. How to make your own judgments about how that information translates into requirements
• This is not a mechanical process—it requires interpretation and decision-making.

🧭 Overview

🧠 One-sentence thesis

Nonfunctional requirements specify how well software must perform and what constraints it must respect, using measurable quality attributes and externally or internally imposed limits to guide development priorities throughout a project.

📌 Key points (3–5)

• What nonfunctional requirements describe: how well the software performs or what constraints it must follow, not what it does.
• Quantifiable thresholds: each nonfunctional requirement should include a measurable quantity to make it testable.
• Two main categories: quality attributes (performance characteristics like reliability, maintainability) and constraints (limits on technology, platforms, or data handling).
• Common confusion: quality attributes vs constraints—quality attributes are often chosen internally by the team, while constraints are typically mandated externally.
• Why they matter: they help teams prioritize what qualities matter most and maintain standards throughout the project duration.

🎯 What nonfunctional requirements are

🎯 Core definition

Nonfunctional requirements describe how well the software needs to perform or what constraints it must respect.

• They are distinct from functional requirements (which describe what the software must do).
• They focus on performance levels and boundaries rather than features.
• Example: "Response time should be a few seconds or less in all operating environments."

📏 The importance of quantities

• The excerpt emphasizes that each nonfunctional requirement has a quantity.
• Quantities make requirements testable, which is a criterion for good requirements.
• Example: "The software must be available 24 hours a day, seven days a week, and must have an uptime of 99.99%"—the 99.99% is the measurable threshold.

🏆 Quality attributes

🏆 What quality attributes are

Quality attributes are words for describing "a service or performance characteristic of software."

• They represent different dimensions of software quality.
• Each can be converted to a scale with measurable values.
• Teams select and prioritize quality attributes based on what matters most to the project.

🔧 Common quality attributes

Quality Attribute	What it measures
Maintainability	Amount of effort needed for developers to update, refactor, or modify code
Portability	Amount of effort needed to run software on different platforms
Reliability	How often the software's functions succeed or fail
Efficiency	Number of resources the software requires
Integrity	How frequently the software loses data
Memorability	Amount of time users must spend relearning functionality
Flexibility	Number of different ways the software can be used
Interoperability	Ease with which the software can integrate with other software
Reusability	Extent to which code can easily be used to solve other problems

📊 Converting attributes to requirements

• Each quality attribute can be converted to a scale with minimum and maximum values.
• Example: for reliability of a single function, 0% would be "succeeds 0% of the time" and 100% would be the opposite.
• A nonfunctional requirement defines a performance threshold on this scale.
• Example: "The function must have high reliability (succeeds >99% of the time)."

🎯 Using quality attributes throughout the project

• When teams select quality attributes, they are prioritizing what qualities matter most.
• Teams should keep these attributes and corresponding nonfunctional requirements in mind for the project's duration.
• If software doesn't meet nonfunctional requirements, either the software or the threshold needs to change.

🚧 Constraints

🚧 What constraints are

• Some nonfunctional requirements are not about quality attributes but about staying within constraints.
• They represent limits or boundaries that must be respected.

🚧 Types of constraints

The excerpt lists several example types:

• Technology constraints: limiting programming languages, frameworks, databases, API types, etc.
• Platform constraints: limiting what platforms are targeted (e.g., mobile versus desktop, iOS versus Android).
• Change constraints: limiting what about the software can change (e.g., for backward compatibility).
• Code-writing constraints: limiting how code can be written (e.g., following particular coding and documentation standards).
• Data-handling constraints: limiting how data can be handled (e.g., must only be stored on US servers).

🔍 Constraints vs quality attributes

Key distinction:

• Constraints are often externally mandated (imposed from outside the team).
• Quality attributes can be chosen internally by the team.

Don't confuse: both are nonfunctional requirements, but their source and nature differ—constraints are typically non-negotiable boundaries, while quality attributes represent performance goals the team selects.

🧭 Overview

🧠 One-sentence thesis

Functional requirements describe what the software must do, and they can be written in multiple formats—including user stories and use cases—each with specific standards to ensure clarity and completeness.

📌 Key points (3–5)

• What functional requirements specify: the behaviors and actions the software must perform under specific conditions.
• Multiple formats exist: plain statements, user story format (common in Agile), given-when-then format (for acceptance criteria), and use cases (more formal).
• User stories follow a structure: "As a [role], I want [functionality] so that [benefit]" and should meet INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable).
• Common confusion: functional requirements (what the software does) vs nonfunctional requirements (quality attributes and constraints); also, user stories vs acceptance criteria—acceptance criteria define when a user story is "done."
• Completion is defined by acceptance criteria: a set of statements (often in given-when-then format) that must be true for a user story to be considered complete.

📝 What functional requirements are

📝 Core definition

Functional requirements: "a description of a behavior that a system will exhibit under specific conditions."

• They describe what the software must do, not how well it does it (that's nonfunctional).
• They focus on specific actions, inputs, outputs, and system responses.
• Example: "When the 'register' button is activated, the user's information is added to the database and a 'thank you for registering' screen displays."

🔀 Different formats for writing them

The excerpt presents several formats, each with different emphases:

Format	Structure	Emphasis
Plain statement	"When [action], [result]"	Direct description of behavior
User story	"As a [role], I want [functionality] so that [benefit]"	User, goal, and motivation
Given-when-then	"Given [context], when [action], then [result]"	Context and conditions
Use case	Template with name, actor, flow of events	Formal, structured interaction sequence

• Plain statement: simply states what should happen when a particular action is taken.
• User story: common in Agile; emphasizes the user, what they're trying to do, and why.
• Given-when-then: incorporates context; commonly used for acceptance criteria.
• Use case: follows a template; more formal and detailed.

📖 User stories in depth

📖 What user stories are

User stories: a method for specifying functional requirements that describes a small piece of the software's functionality in a simple and easy-to-read sentence.

• Written in plain English so nontechnical people (users, clients, stakeholders) can understand them.
• Describe a small piece of functionality, not the entire system.
• Can be written on index cards or entered into project management systems (Jira, Asana, etc.).

✍️ The standard user story format

The body follows this template:

As a [ROLE], I want [SOME FUNCTIONALITY] so that I get [SOME BENEFIT]

Example from the excerpt:

• "As a wholesaler, I want to see the wholesale and retail prices when I go to 'product view' so that I know how much money I'm going to make."

🎯 Who writes user stories and why

• Anyone on the team or any project stakeholder might come up with user stories.
• Once initially defined, they start a conversation with the client and team.
• Clients can guide priority setting.
• The conversation is a good time to get more details, which should be added to the card.

🏆 INVEST criteria for good user stories

The INVEST acronym helps remember characteristics of good user stories:

• (I) Independent: Does not have unnecessary dependencies or overlap with other user stories.

  • Bad overlap example: "As a new user, I want to register..." and "As a new user, I want to register using my Google account..." (these overlap).
  • Good independence example: separate stories for viewing registration page, registering via Facebook, registering via Google, storing registration details (some dependencies are okay, but no overlap).

• (N) Negotiable: Encourages discussion and gives developers flexibility.

  • Discourages discussion: "...I want to choose either black or white so that..."
  • Encourages discussion: "...I want to choose from multiple colors so that..."

• (V) Valuable: Fulfills a user need.

  • Does not fulfill need: "...I want to watch a little race car drive around the screen so that I can do something fun while requesting API end points."
  • Fulfills need: "...I want to import my API end point requests so that my requests take less time and are less tedious."

• (E) Estimable: Can be given a time estimate.

  • Difficult to estimate: "...I want enough encouragement to register so that I'll register."
  • Easier to estimate: "...I want to compare plan pricing so that I can decide which plan to choose."

• (S) Small: Can fit into a single development period (e.g., a two-week Sprint).

  • Probably too large: "...I want to play chess on my phone so that I have something to do while waiting at the pharmacy."
  • Smaller: "...I want to move my pawn so that I can take my turn in chess."

• (T) Testable: Possible to determine it's done.

  • Difficult to determine: "...I want to be satisfied with my experience so that I will want to sign up."
  • Less difficult: "...I want to try out the AI text generator without registering first so that I can decide whether to subscribe."

Note: There is overlap between INVEST and general characteristics of good requirements, but INVEST is easier to remember.

✅ Acceptance criteria and Definition of Done

Acceptance criteria: a set of statements that, when true, indicate that the user story has been completed.

• Negotiated with the client and added to the user story.
• They establish the Definition of Done (DoD) for the user story.
• Commonly written in given-when-then format.

Example from the excerpt (for user story US-023: "As an admin, I want to disable comments..."):

• "Given the user is logged in as a user, when they navigate to 'Settings,' then there is a 'Disable Comments' button."
• "Given the user is on the 'Settings' page, when they activate 'Disable Comments,' then a status message appears that indicates the action was successful. The message appears within 10 milliseconds."
• "Given the user has activated 'Disable Comments,' when they navigate to a 'Post' page, then 'Comments disabled' appears in the 'Comments' section, and no comments are showing."

When is a user story done?

• Once each of the acceptance criteria are confirmed to be done, the user story can be considered "DONE-done."
• Ideally, testing the acceptance criteria can be automated (the excerpt provides pseudocode for testing an acceptance criterion).

Don't confuse: The user story itself (the "As a..." statement) vs. the acceptance criteria (the specific conditions that must be met for the story to be complete).

📋 Use cases in depth

📋 What use cases are

Use cases: a more formal method of specifying functional requirements; structured descriptions of what a system is required to do when a user interacts.

• Less common in Agile than user stories.
• Follow a template structure.
• More detailed and formal than user stories.

🔧 Required parts of a use case

Every use case must have:

• Name: A short title that often starts with a verb (e.g., "Schedule weekly wellness check"); briefly states the user objective.
• Actor(s): The user or users (human/nonhuman/computer) interacting with the software (e.g., "Medical staff").
• Flow of events: Sequence of actions describing the interaction between the actor and the software (also called "basic course of action" or "success scenario").

Note on actors: Sometimes the actor is implied through the flow (e.g., "Shopper selects the calendar icon"); other times, stated separately (e.g., "Actor: Shopper").

🔧 Additional optional parts

Sometimes included in use cases:

• Identifier: A unique way of referring to the use case (e.g., UC-002).
• Preconditions: What must be true before the flow (e.g., "The shopper has added at least one product to their shopping cart").
• Postconditions: What must be true after the flow (e.g., "The shopper received an order confirmation email").
• Business relevance: Justification for why the use case exists.
• Dependencies: Other use cases this use case relies on (the unique identifier is handy here).
• Extensions: Contingencies, alternate routes, and branches to other use cases.
• Priorities: The importance of the use case.
• Nonfunctional requirements: How well the software must perform during the flow.

📄 Example use case from the excerpt

Name: Generate list of recovered patients
Actor: Clinician
Flow:

1. Clinician authenticates using smart card.
2. Software confirms user credentials and permissions for specific machine.
3. Software logs access.
4. Software displays patient search.
5. Clinician selects "Advanced Patient Search."
6. Software confirms user access permissions for advanced search page.
7. Clinician selects ailment and patient status.
8. Clinician executes search using "Search" button.
9. Software returns results.
10. Software logs query.

This example uses a simple template; more complex templates can include the optional parts listed above.

📦 Requirements specification documents

📦 What requirements specification is

Requirements specification (as a process): the process of writing down requirements.

Requirements specification (as a noun): the document that contains the requirements.

• Also called a software requirements specification (SRS).
• Can contain both functional and nonfunctional requirements.

🔀 SRS vs SDD

Don't confuse:

• SRS (Software Requirements Specification): what the software should be.
• SDD (Software Design Document): what the software is.
• There is often overlap between these two documents.

The excerpt recommends looking at real SRS examples to learn about them and provides several freely available examples (for apps, data systems, PDF tools, library software, etc.).

🧭 Overview

🧠 One-sentence thesis

Requirements specification is the process of documenting what software should do (functional) and how well it should perform (nonfunctional), typically captured in a Software Requirements Specification (SRS) document that serves as the foundation for development.

📌 Key points (3–5)

• What requirements specification means: both the process of writing down requirements and the document (SRS) that contains them.
• Two main requirement types: functional requirements describe behaviors under specific conditions; nonfunctional requirements describe properties, characteristics, or constraints the system must exhibit.
• Common confusion: SRS vs SDD—the SRS describes what the software should be, while the Software Design Document (SDD) describes what the software is; these often overlap.
• Multiple formats for functional requirements: given-when-then format, user stories (used in Agile), and use cases (less common in Agile).
• Standards for good requirements: correct, unambiguous, complete, consistent, ranked, verifiable, modifiable, and traceable; user stories follow INVEST (independent, negotiable, valuable, estimable, small, testable).

📋 Use cases as formal specifications

📋 What use cases are

Use cases: structured descriptions of what a system is required to do when a user interacts.

• They are a more formal method of specifying functional requirements than user stories.
• Less common in Agile development.
• Provide a detailed sequence of actions describing interaction between actor and software.

🔧 Required parts of every use case

Every use case must include three core elements:

Part	Description	Example
Name	Short title starting with a verb; states user objective	"Schedule weekly wellness check"
Actor(s)	User(s) interacting with software (human/nonhuman/computer)	"Medical staff"
Flow of events	Sequence of actions describing interaction	Also called "basic course of action" or "success scenario"

• The actor may be implied in the flow (e.g., "Shopper selects the calendar icon") or stated separately (e.g., "Actor: Shopper").

🔧 Optional parts of a use case

Additional elements sometimes included:

• Identifier: unique reference (e.g., UC-002)
• Preconditions: what must be true before the flow (e.g., "The shopper has added at least one product to their shopping cart")
• Postconditions: what must be true after the flow (e.g., "The shopper received an order confirmation email")
• Business relevance: justification for why the use case exists
• Dependencies: other use cases this one relies on (the unique identifier is handy here)
• Extensions: contingencies, alternate routes, and branches to other use cases
• Priorities: the importance of the use case
• Nonfunctional requirements: how well the software must perform during the flow

📄 Requirements specification documents

📄 What an SRS is

Requirements specification (noun): the document that contains the requirements, also called a Software Requirements Specification (SRS).

• The term "requirements specification" refers both to the process of writing down requirements and to the document itself.
• An SRS can contain both functional and nonfunctional requirements.
• The excerpt recommends looking at actual SRS examples as the best way to learn.

🔀 SRS vs SDD distinction

Don't confuse these two document types:

Document	What it describes	Focus
SRS (Software Requirements Specification)	What the software should be	Requirements and desired behavior
SDD (Software Design Document)	What the software is	Actual design and implementation

• There is often overlap between these two documents.
• Example: An SRS might specify "the system must respond within 2 seconds," while an SDD might describe the caching architecture that achieves this.

📚 Available SRS examples

The excerpt lists freely available SRS examples for reference:

• SRS for apps and a data repository for distributing manufacturing data
• SRS for data system that assesses conservation practices
• SRS for an app that splits and merges PDFs
• SRS for software that processes electroencephalography data
• SRS for library software

(The excerpt notes that if links are broken, the Wayback Machine can be used.)

📊 Summary of requirement types and formats

📊 Two main requirement types

Functional requirement: "a description of a behavior that a system will exhibit under specific conditions."

Nonfunctional requirement: "a description of a property or characteristic that a system must exhibit or a constraint that it must respect."

Quality attributes: words for describing "a service or performance characteristic of software."

📝 Formats for functional requirements

The excerpt identifies three main formats:

1. Given-when-then format: used for writing user story acceptance criteria
2. User stories: used in Agile software development
3. Use cases: structured descriptions (less common in Agile)

• A set of acceptance criteria determines whether a user story has been completed (Definition of Done).

✅ Standards for good requirements

General requirements should be:

• Correct
• Unambiguous
• Complete
• Consistent
• Ranked for importance and/or stability
• Verifiable
• Modifiable
• Traceable

User stories follow INVEST:

• Independent
• Negotiable
• Valuable
• Estimable
• Small
• Testable

🧭 Overview

🧠 One-sentence thesis

Use cases are structured descriptions of user-system interactions that specify functional requirements, while requirements specification documents (SRS) capture both functional and nonfunctional requirements to define what the software should be.

📌 Key points (3–5)

• Use cases structure: formal method with required parts (name, actor(s), flow of events) and optional parts (preconditions, postconditions, extensions, etc.).
• Two main requirement types: functional requirements describe system behaviors under specific conditions; nonfunctional requirements describe properties, characteristics, or constraints.
• Common confusion: SRS (software requirements specification) vs SDD (software design document)—SRS defines what the software should be; SDD defines what the software is.
• Quality standards: good requirements should be correct, unambiguous, complete, consistent, ranked, verifiable, modifiable, and traceable; user stories follow INVEST (independent, negotiable, valuable, estimable, small, testable).
• Multiple formats exist: functional requirements can be written as given-when-then, user stories (Agile), or use cases (less common in Agile).

📋 Use case structure

📋 Required parts every use case must have

Part	Description	Example from excerpt
Name	Short title starting with a verb, stating user objective	"Schedule weekly wellness check"
Actor(s)	User(s) interacting with software (human/nonhuman/computer)	"Medical staff"
Flow of events	Sequence of actions describing actor-software interaction	Also called "basic course of action" or "success scenario"

• The actor may be stated separately (e.g., "Actor: Shopper") or implied through the flow (e.g., "Shopper selects the calendar icon").

🔧 Optional parts sometimes included

• Identifier: unique reference (e.g., UC-002)
• Preconditions: what must be true before the flow
  • Example: "The shopper has added at least one product to their shopping cart"
• Postconditions: what must be true after the flow
  • Example: "The shopper received an order confirmation email"
• Business relevance: justification for why the use case exists
• Dependencies: other use cases this one relies on (the identifier helps here)
• Extensions: contingencies, alternate routes, branches to other use cases
• Priorities: importance ranking
• Nonfunctional requirements: how well the software must perform during the flow

⚠️ Use case adoption note

Use cases are less common in Agile development; the excerpt provides only a summary of their structure.

📄 Requirements specification documents

📄 What requirements specification means

Requirements specification: the process of writing down requirements; also refers to the document containing the requirements.

• The document may be called a software requirements specification (SRS).
• An SRS can contain both functional and nonfunctional requirements.

🔀 Don't confuse: SRS vs SDD

Document type	What it defines	Key distinction
SRS (Software Requirements Specification)	What the software should be	The requirements
SDD (Software Design Document)	What the software is	The implementation

• There is often overlap between these two documents.
• The excerpt recommends looking at real SRS examples to learn (it lists several freely available examples for apps, data systems, PDF tools, and library software).

🎯 Requirement types and quality standards

🎯 Two main types of requirements

Functional requirement: "a description of a behavior that a system will exhibit under specific conditions" (Wiegers & Beatty, 2013, p. 599).

Nonfunctional requirement: "a description of a property or characteristic that a system must exhibit or a constraint that it must respect" (Wiegers & Beatty, 2013, p. 600).

Quality attributes: words for describing "a service or performance characteristic of software" (Wiegers & Beatty, 2013, p. 601).

✅ Standards for good requirements

Good requirements should be:

• Correct
• Unambiguous
• Complete
• Consistent
• Ranked for importance and/or stability
• Verifiable
• Modifiable
• Traceable

✅ INVEST acronym for user stories

INVEST helps remember standards for good user stories:

• Independent
• Negotiable
• Valuable
• Estimable
• Small
• Testable

🔄 Functional requirement formats

🔄 Three main formats mentioned

1. Given-when-then format: used for writing user story acceptance criteria
2. User stories: used in Agile software development
3. Use cases: structured descriptions (less common in Agile)

📐 Acceptance criteria and Definition of Done

• A set of acceptance criteria determines whether a user story has been completed.
• This is called the Definition of Done.
• The given-when-then format is specifically used for writing these acceptance criteria.

🧭 Overview

🧠 One-sentence thesis

Diagrams help software teams both plan new software and document existing software by communicating structure and design clearly to various audiences.

📌 Key points (3–5)

• Two main uses: planning software before creation and describing software after creation.
• What makes diagrams effective: they must communicate clearly and at an appropriate level of detail for the intended audience.
• Multiple audiences: developers, managers, new team members, integration partners, end users, and students all need different perspectives.
• Common confusion: more detail is not always better—automatically generated diagrams can include too much detail and become less useful for communication.
• Core purpose: diagrams exist to communicate something about your software to somebody; if the audience doesn't understand, the diagram has failed.

📋 Two major ways diagrams help

🛠️ Planning software you will create

Diagrams can help you plan software you will create.

• Once planning diagrams are created, they serve multiple purposes:
  • Communicate to the development team what will/should be implemented
  • Evaluate whether your plans are good (e.g., are clear, logical, reflect desired quality attributes)
• The diagram becomes a blueprint before any code is written.
• Example: A team creates diagrams to decide if their architecture is logical before starting implementation.

📚 Describing software already created

Diagrams can help you describe software you've already created.

• Already-created software benefits from diagrams for:
  • Documentation: making the software understandable to others
  • Evaluation: assessing how satisfactory the software design is
• The purpose is always to communicate something about your software to somebody.
• Some IDEs can automatically generate diagrams from code, making documentation maintenance easier and more likely to happen.

👥 Understanding your audience

👥 Who might read your diagrams

The excerpt lists many different audiences you could be trying to communicate with:

Audience type	Why they need diagrams
Other developers on the project	Understanding current structure
Supervisor or manager	Oversight and evaluation
Developers interested in joining	Onboarding and assessment
Developers integrating with your system	Understanding interfaces
Curious end users	General understanding
Students of software engineering	Learning examples

🎯 Tailoring to audience needs

• Different audiences require different levels of detail.
• The same diagram may not work for all audiences.
• Example: A manager may need high-level structure, while a developer integrating with your system needs detailed interface information.

✅ Requirements for effective diagrams

✅ Must communicate clearly

To be helpful, diagrams must communicate clearly and at an appropriate level of detail for your intended audience.

• Clarity is non-negotiable: if your intended audience does not understand your diagram—or misunderstands it—your diagram has failed.
• "Appropriate level of detail" means matching the diagram's complexity to what the audience needs.
• Don't confuse "more information" with "better communication"—too much detail can obscure the message.

⚠️ When diagrams fail

• A diagram fails when the audience doesn't understand it.
• A diagram also fails when the audience misunderstands it (incorrect interpretation may be worse than no diagram).
• Automatically generated diagrams can sometimes have more detail than you want, making them less good for communicating.
• Example: An auto-generated diagram showing every private method and field may overwhelm a manager who only needs to understand major components.

🧭 Overview

🧠 One-sentence thesis

Diagrams succeed only when they communicate clearly and at an appropriate level of detail for the intended audience.

📌 Key points (3–5)

• Core requirement: diagrams must communicate clearly to be helpful.
• Detail level matters: the amount of detail must match what the audience needs.
• Failure condition: if the audience does not understand or misunderstands the diagram, it has failed its purpose.
• Common confusion: more detail is not always better—automatically generated diagrams can have too much detail, making them less effective for communication.

🎯 The two essential qualities

🔍 Clarity

• A diagram must communicate clearly to its intended audience.
• Clarity is not optional—it is the fundamental requirement for a diagram to be helpful.
• If the audience cannot understand the diagram, the diagram has failed, regardless of how technically accurate or detailed it is.

📏 Appropriate level of detail

• The diagram must present information at a level of detail that suits the intended audience.
• Too much detail can overwhelm or obscure the main message.
• Too little detail may leave the audience without the information they need.
• Example: automatically generated diagrams from code often contain more detail than needed, making them "less good for communicating" (as noted in section 4.5).

⚠️ When diagrams fail

❌ Misunderstanding or lack of understanding

If your intended audience does not understand your diagram—or misunderstands it—your diagram has failed.

• The excerpt emphasizes that failure occurs in two scenarios:
  • The audience does not understand the diagram at all.
  • The audience misunderstands the diagram (thinks it means something different from what was intended).
• Both outcomes mean the diagram has not fulfilled its communication purpose.

🎭 Audience-specific success

• Success is defined relative to the intended audience, not in absolute terms.
• Different audiences (developers, managers, students, end users) may need different levels of detail and different presentation styles.
• A diagram that works well for one audience may fail for another.

🧭 Overview

🧠 One-sentence thesis

UML provides a standardized family of graphical notations that help software professionals plan, describe, and communicate about software design through diagrams, though it requires balancing detail with clarity.

📌 Key points (3–5)

• What UML is: a family of graphical notations for describing and designing software through diagrams, especially applicable to object-oriented software.
• Why it helps: forces structured thinking about design, provides views at different levels, and creates a common language between professionals.
• Common confusion: UML notation varies in practice—developers make mistakes or adapt it, so providing legends or explanations helps avoid misunderstandings.
• Key tradeoff: diagrams must communicate clearly at an appropriate level of detail, or they fail; too much detail or time spent can make them less useful than other communication methods.
• Historical context: first published 1994, became an OMG standard in 1997, ISO standard in 2005, currently on version 2.

📐 What UML is and its scope

📐 Definition and applicability

Unified Modeling Language: a family of graphical notations for describing and designing software through diagrams.

• It is especially applicable to object-oriented software, but some parts work for many types of software.
• Different UML notations are used for different types of UML diagrams, each with a specific purpose.
• The excerpt emphasizes it is a "family" of notations, not a single diagram type.

📜 Standardization history

• 1994: first published
• 1997: became a standard of the Object Management Group (OMG)
• 2005: became an ISO standard
• Current version: version 2

🎯 How diagrams help software work

🎯 Planning new software

Diagrams can help you plan software you will create:

• Use them to communicate to the development team what will/should be implemented.
• Use them to evaluate whether your plans are good (e.g., are clear, logical, reflect desired quality attributes).

📚 Describing existing software

Diagrams can help you describe software you've already created:

• Good for documentation purposes.
• Good for evaluating how satisfactory your software is.
• The purpose is to communicate something about your software to somebody.

👥 Diverse audiences

Example audiences for your diagrams include:

• Other developers on the project
• Your supervisor or manager
• Developers who might be interested in joining the team
• Developers who want to integrate with your system
• Curious end users
• Students of software engineering

🤖 Automatic generation

• Depending on the IDE/tools you're using, diagrams can be automatically generated from your code.
• This helps make documentation maintenance easier and more likely to happen.
• Don't confuse: auto-generated diagrams can sometimes have more detail than you want, making them less good for communicating.

✅ Benefits of using UML

🛠️ Dual notation purpose

UML gives you:

1. Notation for designing software so that your implementation will be structured.
2. Notation for describing the existing design of software so that you can evaluate whether the design is any good.

🧠 Forces structured thinking

• UML diagramming forces you to think about software design in a structured way.
• When people try to design software in their minds, they can be sloppy—thinking about only the aspects they want to think about.
• UML can encourage you to face the trickier parts of software design.

🔍 Multiple design levels

• UML diagramming gives you a view of the software at different levels of design.
• Example levels: class level, component level, package level.

🗣️ Common professional language

• UML provides a common language between software professionals.
• Because UML is well known, it gives developers and managers a way to communicate in detail about software.
• Important caveat: expect to encounter variations in how UML notation is used—it can be difficult to remember UML notation; developers will make mistakes or adapt the notation to their own way of thinking.
• Tip: provide a legend or explanation of what your notation means.

📖 Code-free communication

• UML diagrams give you a way to tell people about your software's structure without asking them to look through code.
• This is nice, for example, when onboarding new developers or communicating with managers.

⚠️ Drawbacks and limitations

⚠️ Notation variation problem

• People tend to vary their UML notation, which can cause confusion.
• Tips for avoiding that problem:
  1. Keep your notation basic.
  2. Explain more complex notation.

⏱️ Time investment risk

• Getting UML notation right can take a lot of time.
• Remember that diagrams are for communicating.
• Key principle: if creating the diagram takes longer than explaining the code a different way, the diagram isn't helping.

📊 Auto-generation detail issue

• Some IDEs will automatically generate some types of UML diagrams from your code.
• This is nice because it's easy to regenerate your diagram when your code changes.
• Problem: the generated diagrams can sometimes have more detail than you want, making them less good for communicating.

🎯 What makes diagrams effective

🎯 Core requirements

To be helpful, diagrams must communicate clearly and at an appropriate level of detail for your intended audience.

• If your intended audience does not understand your diagram—or misunderstands it—your diagram has failed.
• The excerpt emphasizes that clarity and appropriate detail level are not optional; they define success or failure.
• Example: a diagram with too much detail may overwhelm a manager; a diagram with too little detail may confuse a developer trying to implement it.

🧭 Overview

🧠 One-sentence thesis

UML provides standardized graphical notation that helps software professionals design, describe, and communicate about software structure in a structured way without requiring others to read code.

📌 Key points (3–5)

• Dual purpose: UML offers notation both for designing new software and for describing existing software design.
• Forces structured thinking: diagramming prevents sloppy mental design by making you confront all aspects, including tricky parts.
• Common language benefit: UML is well-known and gives developers/managers a shared vocabulary for detailed communication.
• Common confusion: people vary their UML notation, which can cause confusion—keeping notation basic and explaining complex parts helps.
• Trade-off: UML diagrams take time to create and maintain, so they're only helpful when they communicate faster than alternative methods.

🎯 What UML provides

🎯 Notation for two stages

UML gives you:

1. Notation for designing software so implementation will be structured.
2. Notation for describing existing software design so you can evaluate whether the design is good.

• These are not the same activity: one is planning forward, the other is documenting/evaluating what already exists.
• Both use the same graphical language, making UML versatile across the software lifecycle.

🔍 Multiple levels of view

• UML diagramming shows software at different levels of design: class level, component level, package level.
• This multi-level view helps you zoom in or out depending on what you need to communicate.
• Example: you might show high-level components to a manager but class-level details to a developer joining the team.

🧠 How UML shapes thinking

🧠 Structured thinking enforcement

UML diagramming forces you to think about software design in a structured way.

• Why this matters: when people design software mentally, they can be sloppy—thinking only about the aspects they want to think about.
• UML can encourage you to face the trickier parts of software design that you might otherwise skip.
• The act of drawing forces completeness: you can't leave blanks or hand-wave details as easily as in your head.

🗣️ Common language for professionals

• UML provides a common language between software professionals.
• Because UML is well-known, it gives developers and managers a way to communicate in detail about software.
• Don't confuse: "common language" doesn't mean everyone uses it identically—expect to encounter variations in how UML notation is used.
  • Developers make mistakes or adapt notation to their own thinking.
  • It can be difficult to remember UML notation perfectly.
  • Mitigation: provide a legend or explanation of what your notation means.

📢 Communication advantages

📢 Code-free communication

• UML diagrams let you tell people about your software's structure without asking them to look through code.
• When this is nice:
  • Onboarding new developers.
  • Communicating with managers (who may not read code fluently).
  • Explaining to developers interested in joining the team or integrating with your system.
  • Documenting for curious end users or students of software engineering.

🎯 Audience-appropriate detail

• The excerpt (from section 4.2) emphasizes that diagrams must communicate clearly and at an appropriate level of detail for your intended audience.
• If your intended audience does not understand your diagram—or misunderstands it—your diagram has failed.
• Example: a detailed class diagram may be right for developers but overwhelming for a manager; a high-level component diagram may be better for the latter.

⚠️ Drawbacks and trade-offs

⚠️ Notation variation and confusion

Problem	Why it happens	How to mitigate
People vary their UML notation	Difficult to remember; developers adapt to their own thinking	(1) Keep notation basic; (2) explain more complex notation

• Variation can cause confusion among readers.
• The excerpt acknowledges this is a real drawback, not just a minor issue.

⏱️ Time and maintenance costs

• Getting UML notation right can take a lot of time.
• Remember: diagrams are for communicating. If creating the diagram takes longer than explaining the code a different way, the diagram isn't helping.
• Maintenance burden: UML diagrams can require a lot of maintenance. If your software design changes frequently, so must your UML diagrams if you want them to be accurate.
• Partial solution: some IDEs (integrated development environments) can automatically generate some UML diagrams from your code, making maintenance easier and more likely to happen.
  • Trade-off with auto-generation: generated diagrams can sometimes have more detail than you want, making them less good for communicating.

🔄 When NOT to use UML

The excerpt (section 4.5) lists drawbacks:

• Notation variation → confusion.
• Time cost → may not be worth it if explaining code directly is faster.
• Maintenance cost → frequent design changes require frequent diagram updates.

Key principle: UML is a tool for communication. Evaluate whether it actually helps communicate faster/better than alternatives for your specific situation.

🧭 Overview

🧠 One-sentence thesis

UML diagramming has significant drawbacks—notation inconsistency, time costs, and maintenance burden—that can outweigh its benefits when diagrams become harder to create and maintain than alternative communication methods.

📌 Key points (3–5)

• Automatic generation trade-off: IDEs can auto-generate UML diagrams from code, but these often contain excessive detail that hinders communication.
• Notation variation problem: people tend to use UML notation inconsistently, causing confusion among readers.
• Time investment risk: creating correct UML diagrams can take longer than explaining code through other means, defeating the purpose of communication.
• Maintenance burden: diagrams require constant updates when software design changes frequently, though some IDE automation can help.
• Common confusion: UML is meant to help communication, but if the diagram creation process is more costly than the communication benefit, it's counterproductive.

⚠️ Core drawbacks of UML

🔄 Auto-generation limitations

Auto-generated UML diagrams: diagrams that IDEs create directly from code.

• The convenience: easy to regenerate when code changes, reducing manual maintenance work.
• The problem: generated diagrams often include more detail than needed for effective communication.
• Why it matters: excessive detail makes diagrams less useful for their primary purpose—helping people understand software structure quickly.
• Example: an IDE might generate a class diagram showing every private method and field, overwhelming a manager who only needs to see major components.

🔀 Notation inconsistency

• The core issue: developers vary how they use UML notation, leading to confusion.
• Why this happens: UML notation can be difficult to remember, so people make mistakes or adapt it to their own thinking.
• Mitigation strategies the excerpt provides:
  1. Keep notation basic (simpler = less room for variation)
  2. Explain more complex notation (provide legends or explanations)
• Don't confuse: UML is supposed to be a "common language," but in practice it requires explanation to avoid misinterpretation.

⏱️ Cost-benefit problems

⏳ Time investment concerns

• The central question: does creating the diagram take longer than explaining the code another way?
• The principle: diagrams are tools for communication, not ends in themselves.
• When UML fails: if getting notation right consumes more time than the communication value it provides, the diagram isn't helping.
• Example: spending hours perfecting a sequence diagram when a 10-minute code walkthrough would communicate the same information more efficiently.

🔧 Maintenance burden

• The challenge: UML diagrams require constant updates to stay accurate.
• When it's worst: software designs that change frequently demand equally frequent diagram updates.
• Partial solution: some IDEs can generate certain UML diagram types from code, reducing manual maintenance.
• The trade-off: this circles back to the auto-generation problem—automated diagrams may have too much detail.

📊 When UML becomes counterproductive

Problem	What happens	Impact on communication
Notation variation	Different developers use different conventions	Readers get confused or misunderstand
Time cost	Creating correct diagrams takes excessive time	Communication goal is defeated
Maintenance load	Frequent design changes require constant diagram updates	Documentation becomes outdated or abandoned
Auto-generation detail	Generated diagrams include too much information	Clarity is lost in excessive detail

🎯 The fundamental tension

• UML's purpose is to communicate clearly about software structure.
• But UML's drawbacks can make it harder to communicate than simpler alternatives.
• The excerpt emphasizes evaluating whether the diagram actually helps: if not, don't use it.

🧭 Overview

🧠 One-sentence thesis

Class diagrams describe a system's classes and their static relationships, showing both the structure (properties) and functionality (operations) of each class in a way that communicates design without requiring code inspection.

📌 Key points (3–5)

• What class diagrams show: classes, their properties (structure like instance variables), operations (functionality like methods), and static relationships between classes.
• Core relationship types: association (one class references another), inheritance (subclass relationships), and multiplicity (how many instances relate).
• Notation details matter: symbols like +/–/# indicate public/private/protected access; arrows show directionality; numbers show multiplicity (e.g., 0..1, 0..*).
• Common confusion: association vs inheritance—association means "has a" (contains a reference), while inheritance means "is a" (subclass relationship).
• Communication purpose: class diagrams let you explain software structure to developers and managers without asking them to read through code.

📦 What class diagrams represent

📦 Core purpose

A class diagram describes a system's classes and the static relationships that exist among them.

• "Static relationships" means the structural connections between classes, not runtime behavior.
• Class diagrams also show properties and operations of a class.
• Properties represent the structure of a class (e.g., instance variables).
• Operations represent the functionality provided by the class (e.g., methods).

🔍 Example scenario

The excerpt provides a three-class example:

• Customer, Order, and SharedOrder classes are related.
• An Order has one Customer, but the same Customer can be on multiple Orders.
• A SharedOrder is a type of Order that can have multiple Customers.
• Classes have attributes (e.g., id) and operations (e.g., getId()).

🔤 Notation elements

🔤 Basic class box

• A class is shown as a rectangle/box.
• Attributes (properties) are listed within the class box.
• Operations (methods) are also listed in the class box.
• Access modifiers:
  • + indicates a public method
  • – indicates private
  • # indicates protected
• The notation includes attribute types (e.g., int, Token), method parameters and return types, and default values for attributes.

📝 Notes

• Notes are for placing comments on class diagrams.
• Represented as a folded-corner rectangle attached to the diagram.

🔗 Relationships between classes

🔗 Association (basic)

Association means that a class contains a reference to an object(s) of the other class in the form of a property.

• Shown as a line connecting two classes.
• In a basic association, the diagram doesn't specify which class references which.
• Example: Class1 and Class2 are connected, but directionality is unclear.

➡️ Unidirectional association

• An arrow indicates directionality: Class1 has a Class2.
• The arrow points from the class that holds the reference to the class being referenced.
• Can include a property name: "Class1 has a property named instance1. It is an instance of Class2."
• Don't confuse: the arrow shows ownership/reference direction, not data flow or method calls.

🔢 Multiplicity

Multiplicity indicates how many instances are involved in a relationship.

Notation	Meaning
0..1	Zero or one instance
1	Exactly one instance
0..*	Zero or more instances
*	Zero or more (shorthand)

• Target multiplicity: how many instances of the target class are referenced.
• Source multiplicity: how many instances of the source class hold the reference.
• Example: "Zero or more instances of Class1 have properties named instance1 containing zero or one instance of Class2."

↔️ Bidirectional association

• Both classes reference each other.
• Shown with a line (no arrow, or arrows on both ends).
• Example: "Class1 has zero or more instances of Class2. Class2 has exactly one instance of Class1."

🧬 Inheritance

• Shown with a line and a hollow triangle/arrow pointing to the parent class.
• Represents an "is a" relationship: Class2 is a subclass of Class1; Class2 is a Class1.
• Don't confuse with association: inheritance means subclass/superclass, not "has a" reference.

🌍 Real-world examples

🌍 Where to find class diagrams

The excerpt lists several actual software projects with class diagrams:

• EvoloPy: An open-source nature-inspired optimization framework in Python.
• Processing: A Python framework for geoprocessing tools in QGIS.
• Java-based GUI for MRUI (medical magnetic resonance spectroscopy).
• RepoMiner: A Python framework to mine software repositories for defect prediction.
• pyfao56: FAO-56 evapotranspiration in Python.

These examples show how class diagrams are used in real projects to document structure.

🧭 Overview

🧠 One-sentence thesis

Sequence diagrams communicate interactions between objects in a single use case or scenario, prioritizing clarity for human audiences over exhaustive implementation details.

📌 Key points (3–5)

• Purpose: describe interactions between objects, typically showing one use case or scenario at a time.
• Audience-first principle: focus on what's most important for your human audience, who have limited capacity for absorbing tiny details and limited time.
• Not for implementation details: sequence diagrams are a type of interaction diagram and are not as good for showing object implementation details.
• Common confusion: participants are usually objects, but can also be users, databases, or other entities—what matters most is communicating with your audience, not following rigid rules.
• When to use notation elements: for example, use return arrows only when they help communicate something important about the interaction.

🎯 What sequence diagrams show

🎯 Core purpose

A sequence diagram describes interactions between objects.

• Usually shows a single use case or scenario, not the entire system.
• Emphasizes interactions (what happens between participants) rather than internal structure.
• Sequence diagrams are a type of interaction diagram.

🚫 What they don't show well

• Object implementation details.
• The excerpt explicitly states sequence diagrams "are not as good for showing object implementation details."
• Don't confuse: class diagrams show structure and relationships; sequence diagrams show time-ordered interactions.

🧑‍🤝‍🧑 Example scenario

The excerpt provides a simple example:

• Participants: instances of Manager, Employee, and Order classes.
• Interactions: Manager asks Employee for status update → Employee complies → Employee creates an Order → Manager asks Employee to close the shop → Employee closes the Order.

📐 Sequence diagram notation elements

📦 Participant (the "columns")

The "columns" of a sequence diagram are each participants. Participants are often objects. The name of the participant goes in the box.

• Represented by a box at the top of a vertical column.
• Flexibility: participants are often objects, but not always.
  • Can be a user (sometimes shown as stick figures without the box if human).
  • Can be a database (though in some cases a database is considered an object).
  • Can be other entities as needed.
• Example: in the excerpt's diagram, Manager, Employee, and Order are participants.

⏱️ Lifeline

Vertical dashed line represents the life span of the participant. Top is beginning of life, and bottom is the end. Life ends when the participant is deleted.

• Runs vertically down from the participant box.
• Top = beginning of life; bottom = end of life.
• Shows the duration during which the participant exists.

💬 Message

Interaction from one participant to another is shown by the solid line with arrow. Often a method call.

• Solid line with an arrow pointing from sender to receiver.
• Represents an interaction, typically a method call.
• Example: Manager → Employee (asking for status update).

📊 Activation bar

Box on lifeline indicates when the participant is active. Indicates method is on call stack.

• A rectangular box overlaid on the lifeline.
• Shows when the participant is actively executing (method is on the call stack).
• Helps visualize which participant is "doing work" at any given time.

↩️ Return

Dashed line with arrow indicates method return. Use only when it helps communicate something important about the interaction.

• Dashed line with arrow, typically pointing back to the caller.
• Selective use: the excerpt emphasizes "use only when it helps communicate something important."
• Don't clutter the diagram with returns unless they clarify the interaction.

🔁 Self-call

Method calling self. Solid line with arrow points back to participant's own lifeline.

• A solid arrow that loops back to the same participant's lifeline.
• Indicates recursion or an internal method call within the same object.

❌ Deletion

End of participant's life. Indicated by an X on the lifeline.

• Marked by an X on the lifeline.
• Shows when the participant is destroyed or goes out of scope.

🧠 Design principles for sequence diagrams

🧠 Know your audience

• The excerpt opens with: "When making any diagram, know your audience and what you're trying to communicate."
• Human audiences have limited capacity for absorbing tiny details and limited time.
• Focus on showing what's most important in a way they will understand.

🎨 Flexibility over rigid rules

• "What's most important when creating diagrams is not following the rules or conventions but communicating with your audience."
• Example: participants don't have to be objects—use whatever makes sense for your scenario.
• Example: return arrows are optional—include them only if they add clarity.

🔍 Comparison: sequence diagrams vs class diagrams

Aspect	Sequence diagrams	Class diagrams
Focus	Interactions over time	Structure and relationships
Good for	Showing one use case/scenario	Showing object implementation details
Participants	Objects, users, databases, etc.	Classes and their associations
Time dimension	Vertical axis = time progression	No time dimension

📚 Real-world examples

The excerpt lists several PDFs containing sequence diagrams for actual software projects:

• Py4JFML: A Python wrapper for IEEE Std 1855-2016.
• COFFEE: An MPI-parallelized Python package for numerical evolution of differential equations.
• Teetool: A probabilistic trajectory analysis tool.
• GEMS: A Python library for automation of multidisciplinary design optimization process generation.

(If links are broken, the excerpt suggests trying the Wayback Machine.)

🧭 Overview

🧠 One-sentence thesis

UML diagrams—particularly class diagrams and sequence diagrams—are communication tools for humans that emphasize selected aspects of code design while intentionally omitting others.

📌 Key points (3–5)

• Purpose: UML diagrams help communicate how code works to humans, not computers.
• Selective emphasis: Each diagram type highlights certain design aspects while leaving out others.
• Two common types: Class diagrams and sequence diagrams are widely used in practice.
• Flexibility over rules: What matters most is communicating with your audience, not strictly following conventions.

📐 Sequence Diagram Components

👤 Participants

Participants: the "columns" of a sequence diagram, often objects but can also be users or databases.

• Each participant appears in a box at the top of its column.
• Users (if human) are sometimes shown as stick figures without boxes.
• Non-object participants like databases are also valid.
• The participant name goes inside the box.

⏱️ Lifeline

Lifeline: a vertical dashed line representing the life span of a participant.

• Top of the line = beginning of life.
• Bottom of the line = end of life.
• Life ends when the participant is deleted.

📨 Messages and interactions

Message: interaction from one participant to another, shown by a solid line with arrow.

• Often represents a method call.
• The arrow direction shows who initiates the interaction.

Activation bar:

• Box on the lifeline indicating when the participant is active.
• Shows that a method is on the call stack.

🔄 Special interaction types

Return:

• Dashed line with arrow indicates method return.
• Use only when it helps communicate something important about the interaction.

Self-call:

• Method calling itself.
• Solid line with arrow points back to the participant's own lifeline.

Deletion:

• End of participant's life.
• Indicated by an X on the lifeline.

🎯 Design Philosophy

💬 Communication over convention

• The excerpt emphasizes that following rules is less important than communicating with your audience.
• Diagrams are tools for human understanding, not for computer execution.
• Flexibility is encouraged when it serves clarity.

🔍 Selective representation

• Each UML diagram type emphasizes some parts of code design.
• Other parts are intentionally left out.
• This selective focus helps manage complexity and highlight what matters for a given discussion.

🧭 Overview

🧠 One-sentence thesis

Monolith architecture represents a single interconnected codebase that cannot easily be divided into multiple independent components, and it naturally arises when code is added without architectural planning.

📌 Key points (3–5)

• What a monolith is: one interconnected codebase that cannot easily be divided into multiple independent components that run separately and are individually useful.
• How monoliths arise: this architecture is so common it can emerge without planning—your first program was likely a small monolith, and adding more code/files/classes makes it bigger unless you change the architecture.
• Common confusion: monolith vs microservices—monoliths run in the same process with tight coupling, while microservices are separate applications running in separate processes.
• Key contrast: microservices offer independence and standardized communication but at the cost of more expensive and potentially less secure communication over networks.

🏗️ Defining monolith architecture

🏗️ Core definition

Monolith software is one interconnected codebase that cannot easily be divided into multiple independent components that run separately and are individually useful.

• The key phrase is "cannot easily be divided"—the codebase is tightly woven together.
• Components are not independently useful; they depend on the whole system.
• The excerpt emphasizes that monoliths typically have code with tight coupling and components that run in the same process.

🌱 How monoliths naturally emerge

• Monolith architecture is so common that it can arise without having to plan.
• Example: Your first computer program was probably a small monolith.
• If you keep adding more code/files/classes/components, the software becomes a bigger monolith—unless you change the architecture.
• Don't confuse: a monolith is not necessarily bad or unplanned; it's simply the default state when components are not architecturally separated.

🔄 Monolith vs microservices comparison

🔄 Structural differences

Aspect	Monolith	Microservices
Codebase	One interconnected codebase	Separate applications
Process	Components run in the same process	Each runs in a separate process
Coupling	Tight coupling	Loose coupling via services
Independence	Components cannot run separately	Each service is individually useful

🔄 Communication differences

• Monolith: Components communicate via direct calls (fast, lightweight).
• Microservices: Often communicate over a network using simple pipes (e.g., REST API with GET, POST, PUT, DELETE).
• The excerpt notes that microservice communication is "dumb pipes"—the communication mechanism is simple, but services themselves handle translating and processing messages.

⚖️ Trade-offs with microservices

✅ Advantages of microservices

• Independence: Each individual service can be updated, tested, launched, and stopped without requiring the same from other components.
  • Example: With some monolithic software, all tests must be run each time a developer commits a change, which can make for a long wait.
  • If a service fails, any software depending on it will be without that service, but the rest of the software needn't be affected.
• Standardized component communication: Service communication pipes can be simple and the same each time.
  • This can make for less thinking, fewer mistakes, and less violation of encapsulation when connecting two components—just use the pipe.

❌ Disadvantages of microservices

• More expensive communication: Components in a monolith can communicate via direct calls (fast, lightweight); in contrast, microservices often communicate over a network.
  • Microservice requests typically need to include request metadata.
  • Because the pipes are "dumb," responses might contain extra data (slower, heavier).
• Potentially less secure communication: Communication over a network can be more prone to interception and alteration.

🧩 Microservice characteristics

🧩 Componentization via services

A component is "a unit of software that is independently replaceable and upgradeable."

A service provides functionality while running in its own process.

• In a microservice architecture, components are services.
• Don't confuse: Even though it provides a service, a library is not a service if you're including its code in your code.
• The key distinction is that a service runs in its own process, while a library's code is embedded in your codebase.

📡 Smart end points and dumb pipes

• The communication pipe within a microservice architecture is simple, and the services themselves take care of translating and otherwise processing messages.
• "Dumb pipes" does not imply simple message contents—the messages can be complex, but it's the job of the services to deal with that.
• Example: Microservices commonly communicate through a REST API, which allows these kinds of messages: GET, POST (create), PUT (update), or DELETE.

🧭 Overview

🧠 One-sentence thesis

Microservice architecture organizes software into separate, independently-running applications that communicate through simple pipes, prioritizing business capabilities and decentralization over the unified codebase approach of monoliths.

📌 Key points (3–5)

• Core definition: Microservices are separate applications, each running in its own process and individually useful, unlike monoliths which are single interconnected codebases.
• Communication philosophy: "Smart endpoints and dumb pipes"—services handle complex processing while communication channels remain simple (e.g., REST API).
• Decentralization principle: Each service can have its own database, tech stack, programming language, and governance, enabling flexibility but introducing consistency challenges.
• Common confusion: A library providing a service is not a microservice if its code is included in your code; true services run in separate processes.
• Design mindset shift: Microservices naturally encourage thinking about failure handling, monitoring, and what happens when individual services fail, rather than whole-system failure.

🏗️ Core characteristics

🔌 Smart endpoints and dumb pipes

The communication pipe within a microservice architecture is simple, and the services themselves take care of translating and otherwise processing messages.

• "Dumb pipes" does not mean simple message contents—messages can be complex.
• The simplicity is in the communication channel itself, not what flows through it.
• Example: Microservices commonly use REST API with standard operations (GET, POST/create, PUT/update, DELETE).
• The services are responsible for interpreting and processing complex message contents.

🧩 Componentization via services

Component: "a unit of software that is independently replaceable and upgradeable." Service: provides functionality while running in its own process.

• In microservice architecture, components are services running in separate processes.
• Don't confuse: A library is not a service if you're including its code in your code—even if it "provides a service."
• Contrast with monoliths: typically have tight coupling and components running in the same process.

Advantages of service-based components:

Advantage	What it means	Example benefit
Independence	Each service can be updated, tested, launched, and stopped separately	Developers don't have to run all tests for every change; if one service fails, others can continue
Standardized communication	Service communication pipes are simple and consistent	Less thinking, fewer mistakes, less encapsulation violation when connecting components

Disadvantages of service-based components:

Disadvantage	Why it happens	Impact
More expensive communication	Components communicate over a network instead of direct calls	Requests need metadata; responses might contain extra data (slower, heavier)
Potentially less secure	Network communication is involved	More prone to interception and alteration

🎯 Organization principles

💼 Organized around business capabilities

Business capability: "the potential of a business resource (or groups of resources) to produce customer value by acting on their environment via a process using other tangible and intangible resources."

• Microservices are organized around business capabilities, not technology layers.
• Contrast: Client-server architecture is organized around technology (client-side, server-side, database)—someone unfamiliar with these technologies wouldn't understand the architecture diagram.

Examples of business capabilities from the excerpt:

• A manufacturer slicing wheat dough into noodle strips for grocery store products
• A loan officer leading customers through securing loans for small businesses
• A pet food distributor shipping cat food to stores
• Software making video files compatible with mobile devices

Key implication: Each microservice can have its own tech stack, including its own database.

🗄️ Decentralized data management

• Each service typically has its own database instead of sharing a centralized one.
• Part of decoupling components, which provides benefits including failure containment.

Trade-off: Eventual consistency

Eventual consistency: with time, each microservice will have the most up-to-date information, but meanwhile, there could be a mismatch.

• If two microservices need to share data, the two copies can become inconsistent.
• Example: One database might not yet have received an update, creating temporary mismatches that could annoy or mislead users.

⚙️ Decentralized governance

• Microservices need only be compatible at their interfaces (communication pipe).
• This leaves flexibility in how each is implemented.

Flexibility benefits:

• Each service can be written in a different programming language
• Reduces weight of tech stack decisions and need for compromise
• Teams can choose optimal language, framework, architecture for each service
• Technologies of each microservice can be independently changed

Monolith advantages in governance:

• Teams might only maintain a small set of technologies (e.g., one framework to update)
• Might not need as broad expertise (e.g., working knowledge of five languages not required)
• Easier to maintain same standards across code when it's part of the same codebase

🛡️ Failure handling mindset

💭 Design for failure

When services run in different processes on different machines, created by different teams using different technologies and standards, that can change how developers think.

Microservice failure thinking:

• Shift from "keeping the whole ship afloat" to service-specific approaches
• Focus on monitoring and logging for individual services
• Design decisions about what to do when a service fails—including what to tell the user

Monolith failure thinking:

• More thought into how to revert quickly if a deployment fails
• Failure might mean no part of the monolith works
• Note: Monoliths can also be designed for failure, but it's not as natural a tendency as with microservices

🔄 Comparison with monolith architecture

🏛️ What is monolith architecture

Monolith software: one interconnected codebase that cannot easily be divided into multiple independent components that run separately and are individually useful.

• This architecture is so common it can arise without planning.
• Example: Your first computer program was probably a small monolith.
• Adding more code/files/classes/components makes it a bigger monolith—unless you change the architecture.

📡 Communication differences

Within a monolith:

• Communication (e.g., between classes and components) can happen in many ways
• Includes direct calls and over a network

Between microservices:

• Communication typically happens over a network (e.g., HTTP requests/responses)
• Through "dumb," standardized communication pipes
• While pipes are less complex, endpoints need to be smarter
• Network communication can be less reliable and less secure

🧭 Overview

🧠 One-sentence thesis

Monolith and microservice architectures differ fundamentally in how they handle communication, deployment, scaling, testing, upgrades, and data storage, with microservices offering more independence and flexibility at the cost of increased complexity in network communication and distributed management.

📌 Key points (3–5)

• Communication difference: Monoliths use direct calls and various methods within the same process; microservices communicate over a network through standardized pipes, which is less reliable but more flexible.
• Deployment and scaling: Monoliths must be deployed all at once and scaled by copying the entire application; microservices can be independently deployed and selectively scaled based on usage.
• Technology flexibility vs. simplicity: Microservices allow each service to use different languages and technologies with independent upgrades; monoliths require maintaining fewer technologies but need broader compatibility.
• Common confusion: Network communication in microservices is "dumb" (standardized pipes), but this means the endpoints must be "smarter"—don't assume simpler pipes mean simpler overall design.
• Database architecture: Monoliths typically use one large database (single point of management but potential bottleneck); microservices have separate data storage per service (more management overhead but better parallelism).

🔗 Communication mechanisms

🔗 How monoliths communicate internally

• Communication happens within the same application in many ways.
• Methods include:
  • Direct calls between classes and components
  • Communication over a network (when needed)
• Communication typically stays within the same process or codebase.

🌐 How microservices communicate

Microservices communication: typically happens over a network through standardized communication pipes such as HTTP requests/responses.

• The pipes themselves are "dumb" and standardized—they don't contain complex logic.
• Trade-off: Simpler pipes mean the endpoints (the services themselves) need to be smarter to handle the communication logic.
• Drawbacks: Network communication can be:
  • Less reliable than in-process calls
  • Less secure than internal communication

Don't confuse: "Dumb pipes" doesn't mean the overall system is simpler—it shifts complexity from the communication layer to the service endpoints.

🚀 Deployment and scaling

🚀 Deployment differences

Architecture	Deployment approach	Flexibility
Monolith	Must be deployed all at once	Lower—entire application updates together
Microservices	Can be independently deployed	Higher—each service updates separately

• Microservices can potentially be stopped without stopping connected services.
• Example: If one microservice needs an update, you can deploy just that service without redeploying the entire system.

📈 Scaling differences

Monolith scaling:

• When more resources are needed, the entire monolith is copied onto multiple machines.
• Each machine must have enough space, memory, and processing speed to support the entire monolith.
• No selective scaling—you scale everything or nothing.

Microservices scaling:

• More flexible options for resource allocation.
• Services that are used more frequently can be replicated more times.
• Services with lower usage don't need as many replicas.
• Example: If one service handles 90% of traffic, you can run 10 copies of that service but only 2 copies of less-used services.

🧪 Testing and upgrades

🧪 Testing approaches

Microservices testing:

• Each service can be independently tested.
• Tests can focus on individual service functionality.

Monolith testing:

• Testing is influenced by dependencies within the code.
• Dependencies can reach broadly across the software.
• This can make for slow tests because changes in one area may require testing many connected areas.

⬆️ Upgrade strategies

Microservices upgrades:

• Each microservice can be written in a different language (Python, Java, C++, etc.).
• Each can run in different contexts:
  • Different operating systems
  • Different libraries
  • Different versions of libraries
• In theory, this means they can be independently upgraded.
• Example: You can upgrade the Python version for one service without affecting services written in Java.

Monolith upgrades:

• Upgrading may require more care.
• Each component must be compatible with the new context.
• Note: Compatibility concerns can also apply to microservices in some cases.

🗄️ Database architecture

🗄️ Monolith database approach

Monolithic software might have just one database, potentially a very large one.

Drawbacks of single database:

• Can create a bottleneck if multiple parts of the software need to access the database in parallel.
• Slow database backups and restores.
• Other performance and management issues with very large databases.

Advantages of single database:

• Just one place for managing database access accounts.
• Only one database to maintain, back up, and restore.
• Simpler administration overall.

🗄️ Microservices database approach

• Each microservice typically has its own data storage.
• Trade-off: More databases to manage, but better parallelism and no single bottleneck.
• Each service controls its own data independently.

🛠️ Technology stack decisions

🛠️ Microservices flexibility

• Each service can be written in a different language.
• Reduces the weight of tech stack decisions—no need to compromise on a single technology for everything.
• For each service, teams can choose:
  • Optimal programming language
  • Best framework
  • Appropriate architecture
• Technologies of each microservice can be independently changed.

🛠️ Monolith simplicity

• Teams might only need to maintain a small set of technologies.
• Example: If there's only one framework, only one framework needs updates installed.
• Might not need as broad expertise—no need for working knowledge of five different programming languages.
• When code is part of the same codebase, it might be easier to maintain the same standards across the code.

💡 Design philosophy differences

💡 "Design for Failure" mindset

Microservices mindset:

• Services run in different processes on different machines.
• Created by different teams using different technologies and standards.
• This changes how developers think—instead of keeping the whole ship afloat, thinking shifts toward:
  • Service-specific monitoring
  • Service-specific logging
  • Design decisions about what to do when a service fails
  • What to tell the user when a specific service is down

Monolith mindset:

• More thought might be put into how to revert quickly if a deployment fails.
• Reason: Failure might mean no part of the monolith works—it's all-or-nothing.
• Note: Monoliths can also be designed for failure, but that's not as natural a tendency as with microservices.

🧭 Overview

🧠 One-sentence thesis

Monolith and microservice architectures each offer distinct trade-offs: microservices enable independent management and scaling of individual services, while monoliths provide simpler deployment and more reliable direct communication within a single codebase.

📌 Key points (3–5)

• Deployment difference: monoliths must be deployed all at once; microservices can be deployed independently without stopping other services.
• Scaling flexibility: monoliths require copying the entire application to new machines; microservices allow selective replication of heavily-used services.
• Testing and upgrading: each microservice can be independently tested and upgraded (even using different languages/contexts); monoliths face broader dependencies and compatibility constraints.
• Common confusion: database architecture—monoliths typically use one large database (simpler management but potential bottleneck); microservices use separate data storage per service (more complex but avoids bottlenecks).
• Core trade-off: microservices offer modularity and independent management versus monoliths' simpler deployment, direct communication reliability, lower cost, and better consistency.

🚀 Deployment and operation

🚀 How deployment works

• Monolith: the entire software must be deployed all at once.
• Microservices: each service can be deployed independently; one service can potentially be stopped without stopping connected services.
• Example: if you need to update one feature in a monolith, you must redeploy everything; with microservices, you deploy only the affected service.

📏 How scaling works

Architecture	Scaling approach	Resource requirement
Monolith	Copy entire application onto multiple machines	Each machine needs enough space, memory, and processing speed for the entire monolith
Microservices	Replicate individual services as needed	More options: heavily-used services can be replicated more; lightly-used services less

• Don't confuse: scaling a monolith means duplicating everything, even parts that don't need more capacity; microservices let you scale only what's needed.

🧪 Testing and upgrading

🧪 Testing differences

• Microservices: each service can be independently tested.
• Monolith: testing is influenced by dependencies that can reach broadly across the software, which can make tests slower.
• Example: in a monolith, testing one component may require loading or checking many other components due to internal dependencies.

🔧 Upgrading and technology choices

• Microservices:
  • Each service can be written in a different language (e.g., one in Python, another in Java, another in C++).
  • Each can run in different contexts (different operating systems, libraries, library versions).
  • In theory, this means they can be independently upgraded.
• Monolith:
  • Upgrading may require more care.
  • Each component must be compatible with the new context.
  • (Note: compatibility issues can also occur with microservices.)

🗄️ Database architecture

🗄️ Monolith database approach

• Monolithic software might have just one database, potentially a very large one.
• Drawbacks:
  • Can create a bottleneck if multiple parts of the software need to access the database in parallel.
  • Can make database backups and restores slow.
• Advantages:
  • Just one place for managing database access accounts.
  • One database to maintain, back up, and restore.

🗄️ Microservices database approach

• Each microservice typically has its own data storage.
• This avoids the bottleneck problem but increases management complexity (multiple databases to maintain).

⚖️ Core trade-offs

⚖️ Microservices advantages

• Each service is its own application and can be independently managed.
• Communication mechanisms between modules can be standardized.

⚖️ Monolith advantages

• The codebase can be deployed all at once.
• Components can communicate directly (within the same application).
• Direct communication can be:
  • More reliable than communicating between multiple applications over a network.
  • Less expensive.
  • Provide better consistency.

🔍 How to choose

• The excerpt emphasizes that both architectures have different advantages and disadvantages.
• Don't confuse: "better" depends on context—microservices offer modularity and independent scaling; monoliths offer simplicity, reliability, and consistency in communication.

🧭 Overview

🧠 One-sentence thesis

Oregon State University's CASS converted ODOT's TOCS dispatch software from a monolith to microservices to solve inflexibility, slow deployment, database pressure, and technology-stack limitations.

📌 Key points (3–5)

• The user problem: TOCS home screen could not be easily configured for different dispatcher centers with different needs (icy roads vs. fender-benders).
• Developer problems with the monolith: difficult to keep components decoupled (technical debt), could only deploy a few times a year, database performance issues, and limited/deprecated technology choices (.NET Framework).
• The microservice solution: separate applications with their own databases, a message broker using a standard protocol (AMQP), and a modern technology stack (.NET 6).
• Common confusion: microservices vs. monolith trade-offs—monoliths can be deployed all at once and communicate directly (more reliable, less expensive, better consistency), but microservices offer flexibility and independent deployment.
• Key architectural benefit: dedicated databases per service allowed CASS to use JSON for the Profile Service, which was more appropriate than the monolith's relational database.

🏢 Project context and user needs

🏢 Who and what

• Oregon State University (OSU) Center for Applied Systems and Software (CASS): a nonprofit that gives students real-world software development experience through client work.
• Oregon Department of Transportation (ODOT): the client.
• Transportation Operation Center System (TOCS): ODOT's statewide computer-aided dispatch software that helps dispatchers share road emergency information with responders and the public.

👥 The user problem: inflexibility

• Dispatcher centers in different parts of Oregon had different needs.
  • Example: some centers dealt with more icy roads, others with more fender-benders.
• All centers had to use the same home screen, which could not be easily configured.
• This inflexibility was the main problem from a user perspective.

🚧 Developer problems with the monolith

🧩 Difficult to keep components decoupled

• Many different developers worked on the software.
• Technical debt was building up: developers might need to focus on clearing that debt instead of implementing new TOCS features.
• Don't confuse: technical debt is not about money; it refers to the cost of rework caused by choosing quick solutions now instead of better approaches that would take longer.

🐌 Slow deployment cycle

• CASS could only deploy TOCS a few times a year.
• Why: the software had to be tested and deployed in its entirety (a long process), and it was essential for the software to remain stable, especially during times of year with more weather and road hazards.
• Impact: dispatch centers had to wait a long time for new features (e.g., individualized home screens).

💾 Database pressure

• All the dispatch centers' TOCS software was transacting with the same database.
• This caused performance issues.

🔧 Limited and deprecated technology

• Every part of the software had to be compatible with the .NET Framework.
• The technology stack was becoming deprecated: Microsoft stopped releasing updates to the .NET Framework after version 4.8.
• This limited technology choices.

🏗️ The microservice solution

🏗️ Architecture overview

The new architecture of the TOCS homepage integrates with the monolith and consists of separate applications:

Component	Role	Technology
WinGui Gateway	Prepares data from the services for the New Home Screen UI	.NET 6 stack (modern features)
Message Broker	Talks to the services and the Gateway	Apache ActiveMQ using AMQP (standard protocol)
Services	Each is a separate application with its own database	Various (e.g., Profile Service uses JSON)

📡 Message Broker and standard protocols

• The Message Broker uses AMQP (a standard protocol).
• Benefit: it would be feasible to change the Message Broker technology in the future.
• This avoids vendor lock-in and technology inflexibility.

💿 Dedicated databases per service

• Each service has its own database.
• Advantage: CASS could use JSON for the Profile Service, which was more appropriate than the relational database used within the monolith.
• This solves the database pressure problem and allows technology choices tailored to each service's needs.

🚀 Modern technology stack

• The WinGui Gateway uses .NET 6, which gives developers access to modern features.
• This solves the deprecated-technology problem.

⚖️ Trade-offs: monolith vs. microservices

⚖️ When monoliths are better

The excerpt notes that monoliths have advantages:

• Can be deployed all at once.
• Components can communicate directly.
• This can be more reliable, less expensive, and provide better consistency than communicating between multiple applications over a network.

⚖️ When microservices are better

The TOCS case shows microservices solve:

• Inflexibility (different centers can have different configurations).
• Slow deployment (services can be deployed independently).
• Database bottlenecks (each service has its own database).
• Technology lock-in (each service can use appropriate technology).

Don't confuse: microservices are not always better; they introduce network communication overhead and complexity. The choice depends on the specific problems you need to solve.

🧭 Overview

🧠 One-sentence thesis

Paper prototypes can communicate interaction design—not just static layouts—by using movable paper shapes, annotations, and other simple techniques to show what users can interact with, how they interact, and what happens as a result.

📌 Key points (3–5)

• Paper prototypes need not be static: they can show interaction design through creative techniques like cut-out shapes, arrows, annotations, and strings.
• What interaction design communicates: what users can interact with (e.g., a slider), how they interact (e.g., by dragging), and what happens when they do (e.g., an overlay appears).
• Balance elaboration with cost: more elaborate prototypes (e.g., brass brads for spinnable elements) can show more, but simpler prototypes may communicate the concept just as well if the design might change.
• Common confusion: paper prototypes are not limited to one sheet or a single static drawing—they can represent dynamic interactions across multiple screens.

🎨 Techniques for showing interaction

✂️ Cut-out paper shapes

• You can cut out small paper shapes that are easy to move around.
• Example: a small rectangle showing submenu items that appear when a user clicks a button.
• This technique lets you simulate dynamic UI elements without redrawing the entire screen.

🏷️ Arrows and annotations

• Place arrows and annotations directly on your prototype to indicate interaction flows or explanations.
• These visual cues help communicate how elements relate or what happens next.

🧵 Strings and movable elements

• Add strings to show how UI elements may move (e.g., dragging a slider).
• Some designers even use brass brads for spinnable elements.
• Don't confuse: these are enhancements, not requirements—if the design might be rejected, a simpler prototype may save time and still communicate the concept effectively.

🔄 What interaction design communicates

🖱️ What users can interact with

• The prototype should indicate which elements are interactive (e.g., a slider, a button, a menu).
• This helps reviewers understand the affordances of the design.

🤲 How users interact

• Show the interaction method (e.g., by dragging, clicking, tapping).
• Example: a slider that users drag to adjust a value.

📤 What happens when they interact

• Illustrate the result of the interaction (e.g., an overlay appears showing additional information, such as the elevations of each mountain in a photo).
• This completes the interaction loop and helps reviewers understand the system's response.

⚖️ Balancing elaboration and practicality

💡 Keep cost in mind

• More elaborate prototypes (with movable parts, strings, or brass brads) can show more detail.
• However, if the client or user might not like the design, you may have saved time by using a less elaborate prototype that still communicates the concept.
• The key trade-off: elaboration vs. the risk of wasted effort if the design changes.

🛠️ Flexibility over polish

• Paper prototypes are meant to be quick and low-cost.
• Don't confuse: the goal is to gather feedback and iterate, not to create a finished artifact—simplicity often serves that goal better than complexity.

🧭 Overview

🧠 One-sentence thesis

Paper prototypes enable designers to gather user feedback quickly by simulating interactions through swappable drawings and observing how users respond in real time.

📌 Key points (3–5)

• How to use paper prototypes for feedback: give users screen drawings and watch them interact, swapping in new drawings to simulate the interface responding.
• Two feedback modes: let users explore freely or give them specific tasks to complete.
• Think-aloud protocol: ask users to verbalize their thoughts, actions, goals, and concerns as they interact.
• On-the-fly adaptation: if prepared with extra supplies, designers can construct new designs during the session or invite user participation.
• When to gather feedback: either after the user finishes or continuously throughout the interaction.

🎭 How to conduct a paper prototype feedback session

🎭 The basic setup

• Start by giving the user the entry screen drawing (the first screen they would see).
• Each screen design should be on a separate piece of paper so you can swap them in and out.
• The designer acts as the "computer," responding to user interactions by showing the appropriate next screen.

🎯 Two approaches to user interaction

The excerpt describes two ways to structure the session:

Approach	What it means	When to use
Task-based	Give the user a specific goal (e.g., "submit data report")	When testing specific workflows
Exploratory	Let the user interact freely on their own	When discovering how users naturally navigate

🔄 Simulating interaction

• Watch as users tap buttons or otherwise interact with the paper prototype.
• Be ready to quickly swap in other drawings to respond to their actions.
• Example: if the user taps a gear icon, immediately give them the sketch of the settings screen.
• This creates the illusion of a working interface even though it's just paper.

💬 Gathering feedback during the session

💬 Think-aloud protocol

Think-aloud protocol: asking users to verbalize their thoughts and actions as they interact with the prototype.

The excerpt specifies asking users to share:

• What they're doing
• What they're trying to do
• What questions they have at that moment
• What they don't like

This provides real-time insight into user confusion, expectations, and preferences.

⏰ Timing of feedback

Users can provide feedback in two ways:

• After they're done: wait until the interaction is complete, then discuss.
• As they go: use the think-aloud protocol to gather continuous commentary.

Don't confuse: these aren't mutually exclusive—you can combine both approaches in one session.

🛠️ Flexibility and adaptation

🛠️ On-the-fly design changes

If you're prepared with extra supplies and work quickly, you can:

• Construct new designs during the session in response to user feedback.
• Let the user participate in creating or modifying designs if they're interested.

This flexibility is a key advantage of paper prototyping—changes cost almost nothing compared to coded implementations.

⚡ Speed matters

The excerpt emphasizes being "fast" and "ready to quickly swap" drawings.

• The illusion of interaction depends on responsive transitions between screens.
• Preparation (having all necessary screens drawn beforehand) enables smoother sessions.
• Example: if a user taps multiple buttons in sequence, you need to have those corresponding screens ready to show immediately.

🧭 Overview

🧠 One-sentence thesis

Paper prototyping reduces project costs by detecting user interface design flaws before implementation, while the Inclusivity Heuristics provide guidelines for designing technology that works well across diverse cognitive styles.

📌 Key points (3–5)

• Paper prototyping benefits: catches design flaws early, saves time and money, and helps teams communicate with each other, clients, and users.
• Inclusivity Heuristics purpose: guidelines for supporting five cognitive facets that affect how people interact with technology for the first time.
• Five cognitive facets: attitude toward risk, computer self-efficacy, information processing style, learning style, and motivations.
• Common confusion: cognitive facet vs cognitive style—a facet is a dimension (e.g., attitude toward risk), while a style is a specific value on that dimension (e.g., risk-averse).
• How to use the heuristics: through heuristic evaluation, where multiple evaluators independently check whether a design follows the guidelines.

📝 Paper prototyping techniques

✂️ Creating interactive paper prototypes

• Use cut-out paper shapes that can be moved around to simulate dynamic UI elements.
• Add arrows and annotations to show interactions.
• Use strings to demonstrate how UI elements move.
• Some designers even use brass brads for spinnable elements.

Balance effort with value:

• If the client might reject the design, a simpler prototype may communicate just as well.
• Don't over-invest in elaborate prototypes before getting initial feedback.

🔄 Testing with users

The excerpt describes a hands-on testing approach:

1. Give the user the entry screen drawing.
2. Provide either a specific task (e.g., "submit data report") or let them explore freely.
3. Watch as they tap buttons or interact with the prototype.
4. Quickly swap in other drawings to respond to their actions (e.g., show the settings screen when they tap the gear icon).
5. If you're fast and prepared, construct new designs on the fly or let the user participate in creating alternatives.

💭 Think-aloud protocol

Think-aloud protocol: a method where users verbalize their thoughts while using the prototype.

Ask users to share:

• What they're doing
• What they're trying to do
• What questions they have at that moment
• What they don't like

This can happen during the interaction or after they finish.

🌈 Inclusivity Heuristics framework

🎯 What the heuristics are

Inclusivity Heuristics: guidelines for designing technology to work well for a diversity of users.

• They support inclusive design, a methodology that "enables and draws on the full range of human diversity" and includes "learning from people with a range of perspectives."
• The heuristics focus on five cognitive facets involved in how people interact with technology for the first time.
• They help software practitioners support the full range of cognitive styles for each facet.

🧠 The five cognitive facets

Cognitive facet: a dimension of how people interact with technology.

Cognitive style: a specific value on a cognitive facet.

Cognitive Facet	Range
Attitude toward risk	Risk-averse to risk-tolerant
Computer self-efficacy	Low to high
Information processing style	Comprehensive to selective
Learning style	Process-oriented to mindful tinkering to tinkering
Motivations	Task-motivated to motivated by tech interest

Example: A person might have medium attitude toward risk, high computer self-efficacy, selective information processing style, highly variable learning style, and task motivation—these specific values are their cognitive styles.

Don't confuse: A facet is the dimension itself (e.g., "attitude toward risk"), while a style is where someone falls on that dimension (e.g., "risk-averse").

📚 Background and development

• Also called the Cognitive Style Heuristics or GenderMag Heuristics.
• Developed by human-computer interaction researchers at Oregon State University as part of the GenderMag Project.
• Based on more than 40 publications about gender differences in technology use.
• Future expansion may include other diversity dimensions such as socioeconomic diversity and age diversity.

🔍 Heuristic evaluation method

Heuristic evaluation: an inspection method where multiple evaluators independently check whether a technology design follows the heuristics.

The process:

1. Multiple evaluators work independently.
2. Each evaluator checks whether the design follows the heuristics.
3. Evaluators make note of any issues.
4. Results are compared.
5. The output is a combined set of findings.

This method applies to various heuristic sets, including the Inclusivity Heuristics and Nielsen's Heuristics.

🧭 Overview

🧠 One-sentence thesis

The Inclusivity Heuristics are design guidelines developed to help technology work well for users with diverse cognitive styles, initially grounded in research on gender differences in technology use.

📌 Key points (3–5)

• What the heuristics are: guidelines for designing technology to support a diversity of users across five cognitive facets (risk attitude, self-efficacy, information processing, learning style, motivations).
• Origin and scope: developed by the GenderMag Project at Oregon State University, based on 40+ publications on gender differences; future expansion may include socioeconomic and age diversity.
• How they are used: applied through heuristic evaluation—multiple evaluators independently check designs against the heuristics and compile usability issues.
• Unique feature: framed from the perspective of three personas (Abi, Pat, Tim) who represent different cognitive styles.
• Common confusion: cognitive facet vs cognitive style—a facet is a dimension (e.g., risk attitude); a style is a specific value on that facet (e.g., risk-averse).

🎯 What the Inclusivity Heuristics are

🎯 Core definition and purpose

Inclusivity Heuristics: guidelines for designing technology to work well for a diversity of users.

• They support inclusive design, defined as "a methodology... that enables and draws on the full range of human diversity," including learning from people with diverse perspectives.
• The heuristics currently focus on five cognitive facets involved in first-time technology interaction.

🧩 The five cognitive facets

The heuristics address these dimensions:

Cognitive Facet	Range
Attitude toward risk	Risk-averse to risk-tolerant
Computer self-efficacy	Low to high
Information processing style	Comprehensive to selective
Learning style	Process-oriented to mindful tinkering to tinkering
Motivations	Task-motivated to motivated by tech interest

🔍 Cognitive facet vs cognitive style

• Cognitive facet: a dimension or category (e.g., "attitude toward risk").
• Cognitive style: a specific value on that facet (e.g., "medium attitude toward risk").
• Example from the excerpt: "my cognitive styles are medium attitude toward risk, high computer self-efficacy, selective information processing style, a highly variable learning style, and task motivation."
• Don't confuse: the heuristics help support the full range of styles for each facet, not just one style.

🏛️ Origins and development

🏛️ The GenderMag Project

• Also called the Cognitive Style Heuristics or GenderMag Heuristics.
• Developed by human-computer interaction researchers at Oregon State University.
• Grounded in more than 40 publications about gender differences in how people use technology.

🔮 Future expansion

• Currently focused on gender differences.
• Potential future expansion to include:
  • Socioeconomic diversity
  • Age diversity
• The excerpt cites research already exploring these dimensions.

🔧 How the heuristics are used

🔧 Heuristic evaluation method

Heuristic evaluation: a usability inspection method where multiple evaluators independently check whether a technology design follows the heuristics.

• Process:
  1. Multiple evaluators work independently.
  2. Each checks the design against the heuristics.
  3. They note any issues.
  4. Results are compared.
  5. Output: a combined set of usability issues.
• The Inclusivity Heuristics are meant to be used within this method, similar to Nielsen's Heuristics.

👥 Persona-based framing

• A unique characteristic: the heuristics are framed from the perspective of supporting three personas—Abi, Pat, and Tim.
• Persona: a representation of a user or a group of users.
• Each persona has different cognitive styles across the five facets.
• Example: the excerpt mentions that Abi, Pat, and Tim each have distinct cognitive styles (full details available at GenderMag.org).
• Don't confuse: personas can have any gender and picture; they are not fixed to one demographic.

🧭 Overview

🧠 One-sentence thesis

The Inclusivity Heuristics use three personas—Abi, Pat, and Tim—with different cognitive styles to guide designers in building technology that works well for diverse users across five cognitive facets.

📌 Key points (3–5)

• What the heuristics support: five cognitive facets (attitude toward risk, computer self-efficacy, information processing style, learning style, and motivations) that affect how people interact with technology.
• How personas represent diversity: Abi, Pat, and Tim each have different cognitive styles across these facets, representing different user approaches.
• Common confusion: cognitive facet vs cognitive style—a facet is a dimension (e.g., attitude toward risk), while a style is a specific value on that dimension (e.g., risk-averse).
• Why personas matter: framing heuristics from persona perspectives helps designers consider how the same feature affects users differently based on their cognitive styles.
• What the heuristics guide: eight specific design guidelines that help support all three personas' different needs.

🎯 What Inclusivity Heuristics are

🎯 Core definition and purpose

Inclusivity Heuristics: guidelines for designing technology to work well for a diversity of users.

• They are a way to practice inclusive design: a methodology that "enables and draws on the full range of human diversity" and includes "learning from people with a range of perspectives."
• Also called Cognitive Style Heuristics or GenderMag Heuristics.
• Developed by human-computer interaction researchers at Oregon State University as part of the GenderMag Project.
• Based on more than 40 publications about gender differences in technology use; future versions may expand to other diversity dimensions (socioeconomic, age).

🔍 How heuristics are used

• Meant to be used within heuristic evaluation: a usability inspection method where multiple evaluators independently check whether a design follows the heuristics.
• Process: evaluators note issues, compare results, and produce a combined set of usability issues.
• Similar approach to Nielsen's Heuristics (1994).

🧠 Five cognitive facets

🧠 What cognitive facets are

The heuristics currently support five cognitive facets involved in how people interact with technology for the first time:

Cognitive Facet	Range
Attitude toward risk	Risk-averse to risk-tolerant
Computer self-efficacy	Low to high
Information processing style	Comprehensive to selective
Learning style	Process-oriented to mindful tinkering to tinkering
Motivations	Task-motivated to motivated by tech interest

🎨 Cognitive style vs cognitive facet

Cognitive style: a cognitive facet value.

• Don't confuse: a facet is the dimension itself (e.g., "attitude toward risk"), while a style is a specific position on that dimension (e.g., "medium attitude toward risk").
• Example from the excerpt: "my cognitive styles are medium attitude toward risk, high computer self-efficacy, selective information processing style, a highly variable learning style, and task motivation."
• Each person has a cognitive style for each of the five facets.

👥 The three personas

👥 What personas represent

Persona: a representation of a user or a group of users.

• A unique characteristic of the Inclusivity Heuristics: they are framed from the perspective of supporting three personas—Abi, Pat, and Tim.
• Each persona has different cognitive styles across the five facets.
• The personas can have any gender and picture (not fixed).
• Full versions available at GenderMag.org as part of the GenderMag Method.

🎭 Persona cognitive styles

The excerpt shows that Abi, Pat, and Tim differ across the cognitive facets (specific values listed in Figure 7.1, though details not fully provided in excerpt).

Key differences highlighted in the heuristics:

• Motivations: Abi and Pat have a pragmatic, task-focused approach; Tim is enthusiastic about exploring new, cutting-edge features.
• Risk tolerance: Abi is risk-averse; Pat is cautious but open to trying features; Tim is willing to take risks.
• Information processing: Abi and Pat gather and thoroughly review information before acting; Tim dives into the first interesting option and backtracks if necessary.

🛠️ How the heuristics work

🛠️ Heuristic #1: Explain benefits of features

Design goal: Make it easy for Abi and Pat to quickly see the benefits of features and decide if they want to use them; give Tim the ability to quickly figure out what new features do.

Why this matters:

• Abi and Pat use technology only when necessary for specific tasks; they have limited spare time and prefer familiar features.
• Abi avoids features with unknown time costs and risks.
• Pat is cautious but open to trying features if they're relevant to the task.
• Tim wants to discover and explore new features and is willing to use them without prior knowledge.

Cognitive facets supported: motivations and risk tolerance.

Example: The design helps Abi and Pat seek features that help with their task, while Tim seeks features that are interesting.

💰 Heuristic #2: Explain costs of features

Design goal: Give users the ability to assess whether a feature might require excessive time and effort, so Abi and Pat can avoid it or proceed with caution, and so Tim understands the relative amount of risk.

Why this matters:

• Abi and Pat prefer to reduce risk by avoiding features that might require significant time and effort.
• Tim is more open to taking risks and may be willing to invest additional time and effort, even if features aren't directly related to the current task.

Cognitive facet supported: attitudes toward risk.

Example: Indicating that something is "required" helps Abi and Pat decide whether to proceed or quit, and helps Tim understand what other technical configuration might be required.

📊 Heuristic #3: Let users gather information flexibly

Design goal: Make it easy for Abi and Pat to gather as much information as they want; give Tim the ability to quickly gather useful information without processing a lot they don't care about.

Why this matters:

• Abi and Pat approach decision-making by diligently gathering and thoroughly reviewing relevant information before acting.
• Tim prefers to dive right into the first option that catches their interest and pursue it, backtracking if necessary.

Cognitive facet supported: information processing styles.

Don't confuse: comprehensive vs selective processing—comprehensive users want to review all relevant information before acting; selective users want to act quickly on the first interesting option.

🧭 Overview

🧠 One-sentence thesis

The eight Inclusivity Heuristics guide software design to support users with different cognitive styles—represented by the personas Abi, Pat, and Tim—so that interfaces accommodate diverse motivations, risk tolerances, information-processing styles, self-efficacies, and learning approaches.

📌 Key points (3–5)

• Persona-driven framework: the heuristics are framed from the perspective of three personas (Abi, Pat, and Tim), each with distinct cognitive styles.
• Core cognitive dimensions: the heuristics address motivations, risk tolerance, information processing, computer self-efficacy, and learning styles.
• Common confusion: Abi and Pat are both cautious, but Abi is more risk-averse and self-blaming, while Pat is moderately self-efficacious and willing to try alternatives for a while before reverting to familiar features.
• Design goal: make features accessible and understandable for risk-averse, process-oriented users (Abi), pragmatic experimenters (Pat), and risk-tolerant tinkerers (Tim) simultaneously.
• Eight actionable heuristics: each heuristic targets specific cognitive-style differences to reduce barriers and support diverse user needs.

👥 The three personas and their cognitive styles

👤 Abi's profile

• Motivation: pragmatic—uses technology only when necessary for specific tasks.
• Risk tolerance: risk-averse—avoids features with unknown time costs and other risks.
• Information processing: comprehensive—gathers and thoroughly reviews relevant information before acting.
• Computer self-efficacy: lower—tends toward self-blame when problems arise; may stop using unfamiliar features.
• Learning style: process-oriented—prefers systematic, step-by-step approaches.

👤 Pat's profile

• Motivation: pragmatic—uses technology only when necessary; prefers familiar features to maintain focus.
• Risk tolerance: cautious but open—will try new features to determine relevance, but prefers predictable outcomes.
• Information processing: comprehensive—diligently gathers and reviews information before acting.
• Computer self-efficacy: moderate—will attempt alternative methods for a while when problems arise, but prefers familiar features.
• Learning style: tinkering with mindfulness—actively experiments with new features but reflects on each step.

👤 Tim's profile

• Motivation: enthusiastic—eager to discover and explore new, cutting-edge features.
• Risk tolerance: risk-tolerant—willing to use features without prior knowledge of costs or exact functionality.
• Information processing: selective—dives into the first interesting option and backtracks if necessary.
• Computer self-efficacy: higher—tends to blame the technology when problems arise; invests extra time exploring workarounds.
• Learning style: tinkering—learns by experimenting, but can become excessively engrossed and distracted.

🔍 How to distinguish the personas

Dimension	Abi	Pat	Tim
Risk tolerance	Risk-averse; avoids unknowns	Cautious but willing to try	Risk-tolerant; willing to invest time
Self-efficacy	Lower; self-blaming	Moderate; tries alternatives	Higher; blames technology
Information processing	Comprehensive; thorough review	Comprehensive; thorough review	Selective; quick dive-in
Learning style	Process-oriented; step-by-step	Tinkering with reflection	Tinkering; exploration-driven

Don't confuse: Abi and Pat both gather information comprehensively, but Abi is more risk-averse and self-blaming, while Pat has moderate self-efficacy and will persist longer before reverting to familiar features.

🎯 Heuristics 1–2: Explaining benefits and costs

🎁 Heuristic #1: Explain the benefits of using features

Make it easy for Abi and Pat to quickly see the benefits of features and decide if they want to use them, and give Tim the ability to quickly figure out what new and unique features do.

Why this matters:

• Abi and Pat have limited spare time and prefer familiar features unless they clearly understand how new features help complete their tasks.
• Abi avoids features with unknown time costs; Pat is cautious but open to trying features if relevance is clear.
• Tim is enthusiastic about discovering new features and wants to explore them if they're interesting.

Example: A design shows feature descriptions that help Abi and Pat decide whether the feature supports their task, and helps Tim identify interesting, unique features to explore.

💰 Heuristic #2: Explain the costs of using features

Give users the ability to assess whether a feature might require excessive time and effort so that Abi and Pat can avoid it or proceed with caution, and so Tim understands the relative amount of risk.

Why this matters:

• Abi and Pat prefer to reduce risk by avoiding features that might require significant time and effort.
• Tim is more open to taking risks and willing to invest additional time, even for features not directly related to the current task.

Example: A design indicates that "cor launcher" is required, helping Abi and Pat decide whether to proceed or quit, and helping Tim understand what other technical configuration might be required.

📊 Heuristic 3: Information gathering

📚 Let users gather as much information as they want, and no more

Make it easy for Abi and Pat to gather as much information as they want, and give Tim the ability to quickly gather useful information without processing a lot they don't care about.

Why this matters:

• Abi and Pat approach decision-making by diligently gathering and thoroughly reviewing relevant information before acting.
• Tim prefers to dive into the first interesting option and will backtrack if necessary; does not want to process excessive information.

Example: A design allows users to access documentation and keep it open while coding—this helps Abi and Pat fully understand syntax before using it, while Tim can choose to close the documentation.

Don't confuse: Both Abi/Pat and Tim need information, but Abi/Pat want comprehensive access, while Tim wants quick, minimal access without being forced to process everything.

🔄 Heuristics 4–5: Familiarity and reversibility

🏠 Heuristic #4: Keep familiar features available

Allow Abi, Pat, and Tim to engage with familiar features that they have previously used.

Why this matters:

• Abi (lower self-efficacy, risk-averse): tends toward self-blame and will stop using unfamiliar features if problems arise; prefers to avoid wasting time.
• Pat (moderate self-efficacy, risk-averse): will attempt alternative methods for a while, but prefers familiar features that are predictable in outcomes and time required.
• Tim (higher self-efficacy, risk-tolerant): blames the technology and invests extra time exploring workarounds, but still benefits from recognizing which features they have already explored.

Example: A design update is minimal, keeping most features the same—this helps Abi and Pat detect familiar features they're comfortable with, and helps Tim detect which features they have already explored.

↩️ Heuristic #5: Make undo/redo and backtracking available

Offer Abi and Pat the option to undo/redo actions and backtrack, ensuring they feel at ease when taking actions with uncertain consequences; also allow Tim to recover from mistakes.

Why this matters:

• Abi and Pat, being risk-averse, tend to avoid actions that may be difficult to undo or reverse.
• Tim, being risk-tolerant, is willing to take actions that might be incorrect or require reversal.

Example: A design allows users to undo or redo their last action—this helps Abi and Pat feel assured that using the functionality is safe, and helps Tim backtrack in case they make a mistake.

🛤️ Heuristics 6–7: Task paths and alternative approaches

🗺️ Heuristic #6: Provide an explicit path through the task

Offer Abi a well-defined and explicit task process; for Tim and Pat, provide flexibility to bypass step-by-step processes and tutorials.

Why this matters:

• Abi (process-oriented learner): prefers to approach tasks in a systematic, step-by-step way.
• Tim and Pat (tinkering learners): prefer not to be confined by strict, predetermined processes; thrive with freedom to explore and experiment.

Example: A design gives users a clear choice between three paths—a structured process helps Abi feel comfortable, while Pat and Tim can select "custom" if they'd like to tinker.

🔀 Heuristic #7: Provide ways to try out different approaches

Provide Abi with alternative approaches when difficulties arise; also encourage Tim and Pat to explore multiple strategies to solve problems.

Why this matters:

• Abi (lower self-efficacy): tends toward self-blame when problems arise and may stop using the technology altogether.
• Pat (moderate self-efficacy): will attempt alternative methods to succeed for a period.
• Tim (higher self-efficacy): blames the technology and explores numerous workarounds to overcome issues.

Example: A design allows users to chat with a person if they can't find their question on the list—this helps Abi and Pat because they know they have a backup plan, and helps Tim, who might want to report the problem.

🧪 Heuristic 8: Mindful tinkering

🎯 Encourage tinkerers to tinker mindfully

Encourage Tim to avoid excessive tinkering, such as by adding an extra click, to minimize mistakes, allow better absorption of important information, and help Tim stay focused on the task.

Why this matters:

• Tim's learning style revolves around tinkering, but Tim can become excessively engrossed, leading to long distractions.
• Pat, in contrast, embraces active experimentation but does so mindfully, taking time to reflect on each step during the learning process.

Example: A design adds an extra click or confirmation step—this helps Tim avoid making mistakes while tinkering and stay focused on the task at hand.

Don't confuse: Both Tim and Pat tinker, but Pat reflects on each step (mindful tinkering), while Tim can become excessively distracted (needs design support to stay mindful).

📋 Summary of all eight heuristics

#	Heuristic	Primary cognitive dimension	Key personas supported
1	Explain the benefits of features	Motivations, risk tolerance	Abi, Pat (need clarity); Tim (wants to explore)
2	Explain the costs of features	Attitudes toward risk	Abi, Pat (avoid excessive effort); Tim (understand risk)
3	Let users gather information as they want	Information processing styles	Abi, Pat (comprehensive); Tim (selective)
4	Keep familiar features available	Computer self-efficacy, risk tolerance	Abi, Pat (prefer familiar); Tim (recognize explored)
5	Make undo/redo and backtracking available	Attitudes toward risk	Abi, Pat (feel safe); Tim (recover from mistakes)
6	Provide an explicit path through the task	Learning styles	Abi (process-oriented); Tim, Pat (tinkering)
7	Provide ways to try different approaches	Computer self-efficacy	Abi (alternative when stuck); Pat, Tim (explore strategies)
8	Encourage tinkerers to tinker mindfully	Learning styles	Tim (avoid excessive distraction); Pat (already mindful)

Overall goal: The Inclusivity Heuristics are a set of eight software usability heuristics for evaluating and improving the usability of user interfaces across users with different cognitive styles, ensuring that designs accommodate Abi's process-oriented caution, Pat's pragmatic experimentation, and Tim's enthusiastic tinkering.

🧭 Overview

🧠 One-sentence thesis

The Inclusivity Heuristics are eight software usability guidelines designed to evaluate and improve user interfaces so they work well for users with different cognitive styles.

📌 Key points (3–5)

• What they are: A set of eight heuristics focused on cognitive style inclusivity in software design.
• Purpose: To evaluate and improve UI usability across diverse cognitive approaches to learning and problem-solving.
• Core principle: Different users (represented by personas like Abi, Pat, and Tim) have different cognitive styles that affect how they interact with technology.
• Common confusion: Don't assume all users learn or troubleshoot the same way—some need explicit guidance while others prefer exploration.
• Practical application: Each heuristic addresses specific cognitive style differences in areas like feature adoption, information gathering, and problem-solving approaches.

📋 The Eight Heuristics

📋 Complete list

The excerpt presents eight numbered heuristics for inclusive design:

1. Explain (to Users) the Benefits of Using New and Existing Features
2. Explain (to Users) the Costs of Using New and Existing Features
3. Let Users Gather as Much Information as They Want, and No More Than They Want
4. Keep Familiar Features Available
5. Make Undo/Redo and Backtracking Available
6. Provide an Explicit Path through the Task
7. Provide Ways to Try Out Different Approaches
8. Encourage Tinkerers to Tinker Mindfully

🎯 Design philosophy

• Each heuristic addresses specific cognitive style needs
• The heuristics support multiple user personas simultaneously
• They focus on flexibility rather than one-size-fits-all solutions

🧑‍💻 Cognitive Style Personas

🧑‍💻 Three representative users

The excerpt references three personas that represent different cognitive styles:

Persona	Key Characteristic	Example Behavior
Abi	Lower computer self-efficacy	Tends to blame self when problems arise
Pat	Mindful experimenter	Actively experiments but reflects on each step
Tim	High self-efficacy tinkerer	Blames technology, explores workarounds, can get excessively engrossed

🔍 Self-efficacy differences

• Computer self-efficacy affects how users attribute blame when problems occur
• Lower self-efficacy (Abi): self-blame when difficulties arise
• Higher self-efficacy (Tim): blames the technology itself and seeks workarounds
• These differences require different support strategies in design

🛠️ Heuristic #7: Multiple Approaches

🛠️ Core principle

Provide Ways to Try Out Different Approaches

🎯 What it addresses

• Supports users with different computer self-efficacy levels
• Abi needs alternative approaches when the current method fails
• Tim and Pat benefit from exploring multiple problem-solving strategies

💡 Design example

The excerpt describes a design with a chat option:

• Users can chat with a person if they can't find their question on a list
• Helps Abi and Pat: provides a backup plan, reducing anxiety
• Helps Tim: offers a way to report problems
• Example: A help interface that offers both self-service FAQs and direct human contact

🎮 Heuristic #8: Mindful Tinkering

🎮 Core principle

Encourage Tinkerers to Tinker Mindfully

🔄 Learning style differences

• Tim's approach: learns by tinkering but can become excessively engrossed, leading to long distractions
• Pat's approach: experiments actively but mindfully, reflecting on each step
• The heuristic aims to preserve exploration while preventing excessive distraction

🛡️ Design strategy

• Add friction (e.g., an extra click) to help Tim avoid excessive tinkering
• Benefits:
  • Minimizes mistakes
  • Allows better absorption of important information
  • Helps maintain focus on the primary task

💡 Design example

The excerpt mentions a design that "helps Tim avoid making mistakes while tinkering" by requiring deliberate action before potentially disruptive exploration.

⚠️ Don't confuse

• This is not about preventing exploration entirely
• Goal: encourage mindful rather than mindless tinkering
• Balance between freedom to explore and protection from distraction

🧭 Overview

🧠 One-sentence thesis

Code smells signal decay that makes software harder to maintain, encourages more bad code, and builds technical debt that can ultimately threaten project success.

📌 Key points (3–5)

• What code smells indicate: signs that your software is undergoing code decay and needs reorganization.
• Three main harms: smelly code is harder to maintain, leads to more smelly code, and builds up technical debt.
• Common confusion: "if it works, don't change it" vs. reality—working but sloppy code still accumulates debt that grows harder to manage over time.
• The debt spiral: technical debt can force hiring more developers, reduce productivity, require complete redevelopment, or cause project failure.
• The solution approach: refactoring—improving code without changing what it does—pays down technical debt.

🚨 Recognizing code decay

🚨 Warning signs in your thoughts

The excerpt lists specific thoughts that signal your code needs attention:

• "I would never show this code during an interview."
• "I'm going to start over and rewrite this code from scratch."
• "Every time I look at this code, I have to re-figure-out what it does."
• "These comments don't match the code..."
• "Why is this code repeated in three different places?"
• "I want to switch out this component, but that'll break X, Y, and Z in this other place, and I don't want to deal with that."

🔍 What these thoughts reveal

• You recognize the code is disorganized or unclear.
• The code requires repeated mental effort to understand.
• Changes have become risky or painful.
• Don't confuse: feeling embarrassed about code vs. code that actually works—even working code can be smelly and need attention.

💀 Three ways smelly code harms you

💀 Harder to maintain

Smelly code can be harder for you and others to maintain because the code is unclear.

• When code is hard to maintain, developers tend to work around it or re-create the same functionality elsewhere.
• This creates duplication and inconsistency.
• Example: instead of fixing unclear code, a developer writes a new version in another part of the codebase, now there are two places doing the same thing.

🔄 Leads to more smelly code

Smelly code leads to smellier code.

The message problem:

• When you let your code become disorganized, you are giving yourself and others the message that smelly code is acceptable.
• Disorganized code gives an excuse to be lazy coders.

Example from web development:

• You're working with CSS and your style isn't working—somewhere in the code (other CSS, HTML, or JS), your style is being overridden.
• Instead of tracking down the competing code or markup, you use the "!important" property, which forces the style to be applied.
• The reasoning: "The codebase is a mess anyway, so who cares?"
• The reality: your future self will care.

📈 Builds technical debt

Each time you write sloppy code, you are contributing to your project's technical debt.

The "if it works" trap:

• Common belief: "If the code is working, there's never a reason to change it."
• The excerpt says: Wrong.
• Maybe it works now, but as sloppy software grows, it will get more difficult to deal with.

The debt spiral:

Stage	What happens	Impact
Initial debt	Sloppy code accumulates	Harder to work with
Hiring response	Company hires more developers to keep productivity up	Productivity can go down instead
Teaching burden	Old developers struggle to teach new developers	Everyone continues to write sloppy code
End states	Software may have to be redeveloped entirely (doesn't always solve the problem) OR the project could fail	Major cost or total loss

🛠️ What to do about smelly code

🛠️ Refactoring as the solution

Refactoring is when you improve your code without changing what the code does.

• If you can (e.g., your manager allows it), strongly consider refactoring.
• Refactoring is a way to pay down technical debt.
• Key distinction: you improve the code's structure and clarity, but the functionality stays the same.

📚 Scope of the chapter

The excerpt indicates the chapter will cover:

• Code smells about comments.
• Code smells about functions.
• General code smells (e.g., about the code within functions).
• How to fix these smells.
• This is not an exhaustive list; more advice is available in the references.

⚠️ Special warning about comments

⚠️ The over-commenting trap

The excerpt previews the comments section with a key insight:

Too many comments can be as bad as none.

The learning curve:

• Beginners: don't write comments (solving problems is fun, no time for boring comments).
• With experience: see why comments are useful, then jump to the other extreme—too many comments.
• Some explain functions with paragraphs of prose, or even comment each line.
• It feels tedious but seems like "the right thing to do."

🎯 Interview warning

Don't fall into the trap of adding excessive comments to your code before an interview!

• Some prospective employers specifically look for over-commented code (or can't help but see it) as an indicator of poor programming habits.

📉 Two main drawbacks

Comments get out of date quickly:

• If we update the code, then procrastinate on the comments, what we leave can be misleading (to others and our future selves).
• More comments mean greater likelihood some will be ignored.
• Result: some accurate and some inaccurate comments—why would we trust any of the comments?

Commenting straightforward code distracts:

• Writing comments for straightforward code can distract from the important [excerpt cuts off here].
• The implication: comments should focus on non-obvious parts, not clutter the code with explanations of clear logic.

🧭 Overview

🧠 One-sentence thesis

When code shows signs of decay through various "smells," refactoring improves the code's structure without changing its behavior, paying down technical debt before it compounds into unmaintainable software.

📌 Key points (3–5)

• What code smells signal: disorganized code that needs attention, indicated by thoughts like "I'd never show this in an interview" or "I have to re-figure-out what this does every time."
• Why smells matter: they make code harder to maintain, encourage more smelly code, and build up technical debt that can eventually require complete rewrites or cause project failure.
• The refactoring solution: improving code structure without changing what it does is the way to pay down technical debt.
• Comment smells: too many comments can be as bad as none—they get outdated, distract from important information, and may indicate overly complex code.
• Common confusion: more comments ≠ better code; excessive commenting before interviews can signal poor programming habits, not thoroughness.

🚨 Recognizing code decay

🚨 Warning signs in your thinking

Code decay manifests through specific thought patterns that indicate maintenance problems:

• "I would never show this code during an interview"
• "I'm going to start over and rewrite this code from scratch"
• "Every time I look at this code, I have to re-figure-out what it does"
• "These comments don't match the code"
• "Why is this code repeated in three different places?"
• "I want to switch out this component, but that'll break X, Y, and Z in this other place, and I don't want to deal with that"

🔍 What these signals mean

Code decay: when software becomes disorganized and needs to be reorganized.

These thoughts reveal structural problems, not just cosmetic issues—the code has become a maintenance burden.

💰 Why code smells demand attention

💰 Maintenance burden

• Smelly code is harder for you and others to maintain because the code is unclear.
• When code is hard to maintain, developers tend to work around it or re-create the same functionality elsewhere.
• This creates duplication and further confusion.

🔄 The smell cascade effect

Smelly code leads to smellier code through a feedback loop:

• Disorganized code sends the message that smelly code is acceptable.
• It gives developers an excuse to be lazy coders.
• Example: In web development with CSS, when styles don't work due to competing code, instead of tracking down the problem, developers use "!important" to force the style—thinking "the codebase is a mess anyway, so who cares?"
• Don't confuse: accepting one shortcut because "it's already messy" versus maintaining standards—each compromise makes the next one easier.

📈 Technical debt accumulation

The excerpt warns against the "if it works, never change it" mindset:

• Each time you write sloppy code, you contribute to technical debt.
• As sloppy software grows, it becomes more difficult to deal with.
• Companies may need to hire more developers just to keep productivity up.
• Productivity can actually go down because old developers struggle to teach new developers, and everyone continues writing sloppy code.
• Ultimately, the software may have to be redeveloped entirely (which doesn't always solve the problem) or the project could fail.

🔧 The refactoring solution

🔧 What refactoring means

Refactoring: improving your code without changing what the code does.

• It is a way to pay down technical debt.
• The key distinction: structure changes, behavior stays the same.
• If your manager allows it, strongly consider refactoring when you spot code smells.

🗺️ Scope of code smells

The excerpt covers three categories of code smells:

1. Code smells about comments
2. Code smells about functions
3. General code smells (e.g., about the code within functions)

💬 The comment paradox

💬 Too many vs. too few

The excerpt identifies a common learning trajectory:

• Beginners: no comments (solving problems is fun; no time for boring comments)
• After gaining experience: jumping to the other extreme with too many comments
• Explaining functions with paragraphs of prose or commenting each line
• Key insight: too many comments can be as bad as none.

⚠️ Interview warning

Don't fall into the trap of adding excessive comments before an interview:

• Some prospective employers specifically look for over-commented code as an indicator of poor programming habits.
• They can't help but see it as a red flag.

🪲 Three drawbacks of excessive comments

🪲 Comments become outdated quickly

• If you update the code but procrastinate on the comments, what remains can be misleading.
• More comments mean greater likelihood some will be ignored.
• This creates a mix of accurate and inaccurate comments.
• Result: why would anyone trust any of the comments?

🪲 Straightforward code comments distract

• Writing comments for straightforward code can distract from the important comments.
• Comments are most valuable when code was difficult to write, is long, is unique, is complex, or has a "gotcha."
• They should call attention to idiosyncrasies of the code.

🪲 Excessive comments signal complexity

• Writing lots of comments could indicate the code needs to be simplified.
• Ideally, most code should be self-explanatory, so frequent comments are not needed.

🧹 Common comment smells and fixes

🧹 Obsolete Comment

Problem: Comment no longer describes the code.

Fix: Remove or update.

Example from excerpt:

# Comment says "Uses the TwoFish block cipher with 256 bit key size"
# But code calls ThreeFish(512,data)

🧹 Commented-Out Code

Problem: Someone thought they'd need that code later, but the commented-out block is now getting out of date and in the way.

Fix: Remove. If feeling risk-averse, save a backup or use a version-control system.

Why it's smelly: Commenting out code comes with poor assumptions:

• You'll need the code later
• Others will understand why you commented it out
• The surrounding code will continue having the same purpose

🧹 Redundant Comment

Problem: States what would already be immediately apparent to a programmer of any level.

Fix: Remove. Less is more.

Example from excerpt:

getLength()  # gets the length

This comment adds no information beyond what the function name already conveys.

🧹 Long Comment

Problem: Multiple sentences, complicated, goes into a lot of detail.

Fix: Simplify the code to make it more self-explanatory; shorten or remove comment.

Example scenario from excerpt: A comment that explains "This is the first function I made in this module" and goes into detail about Unicode-to-ASCII conversion problems—this level of detail suggests the code itself needs simplification rather than extensive documentation.

🧭 Overview

🧠 One-sentence thesis

Too many comments can be as harmful as none because they get out of date, distract from important information, and often signal that the code itself needs simplification.

📌 Key points (3–5)

• The learning curve: beginners write no comments, then over-correct by writing too many; the goal is a middle ground where code is self-explanatory.
• Why excessive comments hurt: they become outdated quickly, distract from truly important comments, and may indicate overly complex code.
• Common confusion: more comments ≠ better code; straightforward code should not need line-by-line explanation.
• Four code smells: obsolete comments, commented-out code, redundant comments, and long comments—each has a specific refactoring solution.
• Interview risk: over-commented code can signal poor programming habits to prospective employers.

🔄 The comment learning curve

📚 From no comments to too many

• Beginners: often skip comments entirely because solving problems is more fun than documentation.
• After gaining experience: working with others, formal training, or revisiting old projects reveals why comments are useful.
• The over-correction trap: some developers then jump to the opposite extreme—paragraphs of prose or line-by-line comments.
• Don't confuse: "more comments" with "better documentation"; the excerpt emphasizes that excessive comments can be as bad as none.

⚠️ Interview warning

• Some employers specifically look for over-commented code as an indicator of poor programming habits.
• This is something to watch for before submitting code for review or interviews.

🚫 Why too many comments hurt

📅 Comments get out of date quickly

• When code is updated, developers often procrastinate on updating comments.
• Outdated comments become misleading to others and to your future self.
• The trust problem: if some comments are accurate and others are inaccurate, why trust any of them?
• More comments = greater likelihood that some will be ignored during updates.

🎯 Straightforward code doesn't need explanation

• Commenting simple, clear code distracts from the truly important comments.
• When comments help: code that was difficult to write, is long, is unique, is complex, or has a "gotcha."
• Comments should call attention to idiosyncrasies, not restate the obvious.

🔧 Frequent comments signal a deeper problem

• If you need lots of comments, the code itself probably needs to be simplified.
• Ideal code is self-explanatory and requires minimal commentary.

🦨 Four comment code smells

🗑️ Obsolete Comment

A comment that no longer describes the code.

What to do: Remove or update it.

Example:

# Comment says "Uses the TwoFish block cipher with 256 bit key size"
# But the code calls ThreeFish(512, data)

• The comment describes a different algorithm and key size than what the code actually does.

✂️ Commented-Out Code

Code that has been commented out (presumably to save for later) but is now getting out of date and in the way.

What to do: Remove it. If you're risk-averse, save a backup or use version control.

Why it's problematic:

• Assumes you'll need the code later (often false).
• Assumes others will understand why you commented it out.
• Assumes the surrounding code will keep the same purpose.

Example:

# Function has a docstring listing updateTime(), updatePlayers(), updatePoints()
# But the actual implementation just loops through players
# The commented-out structure is misleading

🔁 Redundant Comment

A comment that states what would already be immediately apparent to any programmer.

What to do: Remove it. Less is more.

Example:

getLength()  # gets the length

• The function name already says what it does; the comment adds no value.

📜 Long Comment

Multiple sentences, complicated explanations, excessive detail.

What to do: Simplify the code to make it more self-explanatory; shorten or remove the comment.

Example:

# A multi-sentence comment explaining:
# - This is the first function in the module
# - It takes Unicode input and converts to ASCII
# - Creates a visualization of typing
# - Sometimes meaning is lost in conversion

• This level of detail suggests the function is doing too much or is poorly structured.
• The comment is trying to compensate for unclear code design.

📊 Summary table

Code Smell	What it is	Refactoring action
Obsolete Comment	No longer describes the code	Remove or update
Commented-Out Code	Old code left "just in case"	Remove (use version control instead)
Redundant Comment	States the obvious	Remove
Long Comment	Multiple sentences, excessive detail	Simplify code; shorten or remove comment

🧭 Overview

🧠 One-sentence thesis

Breaking functions into small, single-purpose units (ideally five lines or fewer) dramatically improves code readability, maintainability, and modularity, preventing the common trap of unmaintainable, bug-ridden code that results from letting functions balloon as programs grow.

📌 Key points (3–5)

• The natural trap: programmers often start with a simple function and keep adding features to it as the program grows, causing the function to balloon into an unmaintainable mess.
• Target size: aim for functions of five lines or fewer; more than 10 lines signals a problem.
• Single responsibility: each function should do only what its name suggests—doing many unrelated things is a code smell.
• Common confusion: feeling proud of understanding a complex function's details vs. recognizing that complexity itself is the problem—"understanding the small details of how the function works can even make one feel proud—until the code becomes unmaintainable and bug-ridden."
• Parameter count: more than three or four parameters is a smell; zero parameters is ideal.

🌱 How functions balloon

🌱 The incremental growth pattern

The excerpt describes a typical evolution:

• You start with a simple GUI function that draws a start and stop button.
• You add a menu and settings button → update the same function.
• You add user accounts → the function now checks login status, inactivity levels, shows pop-ups about new features.
• Result: the function balloons into something complex and bug-prone.

🪤 The pride trap

• Understanding all the small details of a complex function can make you feel accomplished.
• But this pride is misplaced: the complexity itself is the problem.
• The excerpt warns: "Understanding the small details of how the function works can even make one feel proud—until the code becomes unmaintainable and bug-ridden."

⚠️ Why it matters even for short programs

The excerpt asks: "If you're only writing a short program, does coding style matter?"

• Answer: "Treating code as disposable is a self-fulfilling prophecy."
• Even small programs benefit from good structure; bad habits compound as code grows.

🔧 Function code smells and refactoring

🔧 Long Function

Code smell: more than 10 lines or so.

Refactoring: Break into multiple functions. Aim for five lines or fewer.

• The excerpt states: "Software made of three to four line functions is amazing to behold!"
• Shorter functions are easier to understand, test, and reuse.

🎯 Function with Many Jobs

Code smell: doing more than what its name suggests, doing things that aren't closely related, doing many things.

Refactoring: Break into multiple functions.

Example from the excerpt:

• Before: updateGUI() does both state updates (time, scores) and display updates (time display, score display, window refresh).
• After: Split into two functions:
  • updateState(): handles updateTime() and updateScores().
  • updateGUI(): handles updateTimeDisplay(), updateScoreDisplay(), and refreshWindow().
• This separates concerns: state logic vs. display logic.

📦 Function with Many Parameters

Code smell: more than four parameters (some say more than three).

Refactoring options:

• Pass an object that combines the parameters.
• Make calls within the function to get the parameter data.
• Break into multiple functions.
• Find another way to reduce parameter count.

The excerpt emphasizes: "Zero function parameters is even better than four!"

Example from the excerpt:

• Before: initOutdoorPlace(floraList, faunaList, temperature, windSpeed, cloudiness, rockiness, birdNoises, grassLength) — eight parameters.
• After: initOutdoorPlace(world1data) — one parameter (an object containing all the data).

🧩 Why fewer parameters matter

• Many parameters make function calls hard to read and error-prone (easy to mix up order).
• Bundling related data into an object clarifies intent and reduces cognitive load.
• Don't confuse: reducing parameter count is not about hiding complexity; it's about organizing related data logically.

🎯 The ideal: small, focused functions

🎯 What "small" means

• Target: five lines or fewer.
• Warning threshold: more than 10 lines.
• The excerpt's praise: "Software made of three to four line functions is amazing to behold!"

🎯 Benefits of small functions

The excerpt lists three key benefits:

• Readability: easier to understand at a glance.
• Maintainability: simpler to update and debug.
• Modularity: easier to reuse and compose.

🎯 How to achieve it

• Constantly ask: "Is this function doing one thing?"
• If a function grows beyond its name's promise, split it.
• If you need many parameters, rethink the data structure.
• The excerpt notes: "To write tidy code, you may have to frequently stop and think about its design."

🧭 Overview

🧠 One-sentence thesis

Code becomes messy quickly without attention, so applying specific refactoring practices—such as eliminating duplication, shortening lines and functions, and using clear naming—keeps software maintainable and readable.

📌 Key points (3–5)

• Why code gets messy: many developers weren't trained to write tidy code initially, and messiness accumulates without regular attention to design and refactoring.
• Duplicate code smell: same code appearing in multiple places should be consolidated into one location (while watching for unwanted dependencies).
• Long lines and inconsistent conventions: lines over ~100 characters should be shortened, and code should follow consistent formatting conventions throughout.
• Vague naming problem: unclear variable/function names should be replaced with descriptive names, even if long, because good names can replace comments.
• Common confusion: shorter isn't always better—"syntactic sugar" (concise elegant syntax) is pointless if nobody can understand it.

🧹 Why code deteriorates

🧹 Root causes of messy code

The excerpt identifies that code "gets messy fast if you're not paying attention."

Key reasons:

• Many developers weren't trained to be neat with code when first learning
• Writing tidy code requires frequently stopping to think about design
• Requires being strict about refactoring regularly
• Better habits develop over time with practice

🔄 The solution approach

To maintain clean code, you must:

• Frequently stop and think about design
• Refactor regularly (not just when convenient)
• Adopt better habits gradually

🔍 Duplicate code problems

🔍 What duplicate code means

Duplicate Code: same code appearing in multiple places.

The refactoring rule: consolidate into one place, but watch out for creating unwanted dependencies.

🔍 How to consolidate duplicates

The excerpt provides a detailed example:

Before: Two functions (updateLevelOfAlarm and react) both check the same condition:

• if (npc.isWalking() && npc.isAlive() && npc.isFriendly())
• This identical logic appears in both places

After:

• Extract the repeated condition into a new function isHarmless(npc)
• Combine the two functions into one react(npc) function
• Extract alarm-setting logic into its own function setLevelOfAlarm(level)

Example: If you have the same three-condition check scattered across multiple functions, create one isHarmless() function that all other functions can call—this way, if the definition of "harmless" changes, you only update one place.

📏 Line length and formatting

📏 Long lines smell

Long Lines: more than 100 characters or so.

Solutions for shortening:

• Break into multiple lines
• Convert to a function call
• Define new variables

📏 Refactoring long conditional example

Before: A single line checking rectangle properties:

if (rectangle.coordinate[1][0] - rectangle.coordinate[2][0] > 500 && rectangle.coordinate[2][1] - rectangle.coordinate[3][1] > 500 && rectangle.isSquare()):

After: Extract calculations into meaningful properties:

if (rectangle.isSquare() && rectangle.width > 500):

The improvement: complex coordinate math is hidden behind a clear width property.

⚖️ When shorter isn't better

The excerpt warns about arbitrary thresholds:

• Rules like "100 characters" or "five lines" are not absolute
• Generally shorter is better, but not always
• Syntactic sugar (concise, elegant built-in syntax) can make code shorter but pointless if nobody understands it

Don't confuse: brevity for its own sake vs. clarity—the goal is understandable code, not just short code.

🎨 Consistency and naming

🎨 Inconsistent conventions smell

Inconsistent Conventions: formatting code differently in different places, or untidily.

Rules for consistency:

• Follow whatever style conventions the code already uses
• For new projects, plan to be self-consistent or follow accepted language conventions
• When adding to another person's code, follow their style even if you prefer differently
• Exception: if their style is sloppy and inconsistent, consider politely fixing it

🎨 Consistency example

The excerpt shows inconsistent formatting:

• Variable naming: whale.isSinging vs. starfish.blockingCamera
• Function naming: activateAudioRecordingDevice() vs. recording_device_off_confirmation_check()
• Brace placement varies between if-statements

After refactoring: consistent capitalization (e.g., Whale.isSinging, Starfish.isBlockingCamera), consistent function naming style, and uniform brace placement.

🏷️ Vague naming smell

Vague Naming: does not communicate what the function, variable, etc. is for.

Solution: Rename it, even if the name becomes long.

Benefit: "Long names can sometimes replace comments" and "Wouldn't it be nice if code read like a book?"

Example transformation:

• Before: a = 100 and b = 2 (completely unclear purpose)
• After: retail_price = 100 and wholesale_multiplier = 2 (immediately understandable)

Don't confuse: long names with verbose names—a long descriptive name is better than a short cryptic one.

📋 Summary checklist

The excerpt provides a quick reference list for cleaning code:

Code smell	Action
Obsolete comment	Remove or update
Commented-out code	Remove
Redundant comment	Remove
Long comment	Simplify, shorten, or remove
Long function (~10+ lines)	Split
Function with many jobs	Split
Function with many parameters	Pass an object, make calls to get data, or split
Duplicate code	Consolidate
Long lines (~100+ characters)	Shorten, convert to function, or define new variables
Inconsistent conventions	Follow existing conventions
Vague naming	Rename

The overall goal: "Cleaning up your code can help make your software sustainable and extensible and can make your teammates happier, too."

🧭 Overview

🧠 One-sentence thesis

Cleaning up code by removing obsolete comments, splitting long functions, consolidating duplicates, and following consistent conventions makes software sustainable, extensible, and easier for teams to work with.

📌 Key points (3–5)

• What code smells are: patterns of poor code quality that should be refactored (duplicate code, long lines, vague naming, inconsistent conventions).
• Comment problems: obsolete, commented-out, redundant, or overly long comments should be removed or updated.
• Function problems: long functions (more than ~10 lines), functions with many jobs, or functions with many parameters should be split or restructured.
• Common confusion: shorter is generally better, but arbitrary thresholds (like "100 characters") aren't universal rules—"syntactic sugar" can make code shorter but less understandable.
• Why it matters: refactoring regularly improves code sustainability and team happiness.

🗑️ Comment-related smells

🗑️ Obsolete or commented-out code

• Obsolete comments: Remove or update comments that no longer reflect the current code.
• Commented-out code: Remove it entirely rather than leaving it in the codebase.
• Don't confuse: commented-out code is different from explanatory comments—the former is dead code that should be deleted.

📝 Redundant and long comments

• Redundant comments: If the comment just repeats what the code already says clearly, remove it.
• Long comments: Simplify, shorten, or remove them.
• The excerpt suggests that long, clear variable names can sometimes replace the need for comments.

🔧 Function-related smells

📏 Long functions

• Threshold: More than approximately 10 lines.
• Solution: Split into smaller functions.
• The excerpt notes that thresholds like "10 lines" are arbitrary guidelines, not absolute rules.

🎯 Functions with too many responsibilities

• Function with many jobs: Split into separate functions, each with a single clear purpose.
• Function with many parameters: Three solutions:
  • Pass an object instead of individual parameters
  • Make calls to get the parameter data within the function
  • Split the function into smaller pieces

🧹 General code quality smells

🔁 Duplicate code

Duplicate Code: the same code appearing in multiple places.

• Solution: Consolidate into one place.
• Warning: Watch out for creating unwanted dependencies when consolidating.
• Example: The excerpt shows before/after code where a repeated conditional check (npc.isWalking() && npc.isAlive() && npc.isFriendly()) is extracted into a single isHarmless(npc) function.

📐 Long lines

• Threshold: More than approximately 100 characters.
• Solutions: Break into multiple lines, convert to a function call, or define new variables.
• Example: The excerpt shows replacing rectangle.coordinate[1][0] - rectangle.coordinate[2][0] > 500 && ... with the clearer rectangle.isSquare() && rectangle.width > 500.

🎨 Inconsistent conventions

• Problem: Formatting code differently in different places, or writing untidily.
• Solution: Follow whatever style conventions the code is already using.
• Best practice: When adding to another person's code, follow their coding style even if you prefer a different way.
• Exception: If their code style is sloppy and inconsistent, consider whether there's a polite way to fix the problem.
• Example: The excerpt shows inconsistent capitalization (whale.isSinging vs Whale.isSinging), brace placement, and function naming (activateAudioRecordingDevice() vs recording_device_off_confirmation_check()).

🏷️ Vague naming

• Problem: Names that don't communicate what the function, variable, etc. is for.
• Solution: Rename it, even if the name becomes long.
• Philosophy: "Wouldn't it be nice if code read like a book?"
• Example: Replacing a = 100 and b = 2 with retail_price = 100 and wholesale_multiplier = 2.

📋 Quick reference checklist

Smell	Action
Obsolete comment	Remove or update
Commented-out code	Remove
Redundant comment	Remove
Long comment	Simplify, shorten, or remove
Long function (>~10 lines)	Split
Function with many jobs	Split
Function with many parameters	Pass object, make calls, or split
Duplicate code	Consolidate
Long lines (>~100 characters)	Shorten, convert to function, or define variables
Inconsistent conventions	Follow existing conventions
Vague naming	Rename

🧭 Overview

🧠 One-sentence thesis

The conclusion expresses hope that the reader is now better equipped for their next software project.

📌 Key points (3–5)

• Main message: The author hopes the reader has gained useful knowledge and skills.
• Target outcome: Readers should feel better prepared to tackle software projects.
• Tone: Brief, encouraging, and forward-looking.

🎯 Core message

🎯 What the conclusion conveys

The excerpt contains only a brief closing statement from the author.

• The author expresses a hope that the material has been helpful.
• The focus is on practical application: "your next software project."
• The phrase "better equipped" suggests the goal was to provide tools, knowledge, or skills.

📚 Context clues

• The conclusion follows a chapter on "Code Smells" (refactoring and code quality).
• A glossary appears after the conclusion, suggesting this is the end of the main content.
• The visual element mentions "The Reader Becoming Better Equipped," reinforcing the educational purpose.

💭 What this tells us

💭 About the book's purpose

• The work is instructional, aimed at helping readers improve their software development practice.
• The brevity suggests the author lets the preceding content speak for itself.
• The forward-looking tone ("your next software project") encourages immediate application of learned concepts.

---

Note: This excerpt contains minimal substantive content—it is a standard closing statement. The surrounding context (code smells chapter and glossary) provides more insight into the book's educational focus on software development practices.