YEARLY UPDATE: Adjust content and add genAI Element

config.yaml

@@ -58,11 +58,13 @@ contact: 'icosden@princeton.edu'
 # - another-learner.md
 
 # Order of episodes in your lesson
-episodes: 
+episodes:
 - introduction.md
 - waterfall.md
 - agile.md
 - scrumban.md
+- choosing.md
+- genai.md
 
 # Information for Learners
 learners: 

episodes/agile.md

@@ -35,79 +35,83 @@ They tend to incorporate other practices to improve software quality.
 We are uncovering better ways of developing software by doing it and helping others do it.
 Through this work we have come to value:
 
-- **Individuals and interactions** over processes and tools
-- **Working software** over comprehensive documentation
-- **Customer collaboration** over contract negotiation
-- **Responding to change** over following a plan
+| We value… | …over… |
+|-----------|--------|
+| **Individuals and interactions** | processes and tools |
+| **Working software** | comprehensive documentation |
+| **Customer collaboration** | contract negotiation |
+| **Responding to change** | following a plan |
 
-(Nearly) everything about Agile Development is based on one value:
-Identify and eliminate sources of **WASTE**.
+Note the phrasing: the items on the right still have value — the items on the left
+just have *more*. (Nearly) everything about Agile is based on one underlying value:
+identify and eliminate sources of **WASTE**.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::::::::  callout
+
+## Agile does not mean "no plan, no docs"
+
+A common misconception is that Agile means skipping planning and documentation.
+It doesn't. Agile teams plan constantly — just in shorter cycles — and they write
+the documentation that genuinely helps. The shift is *when* and *how much*, not
+*whether*.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
 
 ### Individuals and Interactions over Processes and Tools
 
-Good processes and tools are important, but it's more important to make
-sure that people are happy, productive, and communicating.
-If a process or tool isn't working for people, change it!
-Agile methods favor lightweight, widely accessible tools over fancy, expensive software packages.
-This can mean collaborative whiteboards in public areas and simple text formats
-like markdown and restructuredText for documents.
-Agile methods promote a pace for software development that can be
-sustained indefinitely and without heroics.
-
-Agile methods incorporate very regular communication of status, identification of
-issues, and retrospectives/postmortems on efforts.
-This is preferably in face-to-face interactions like daily interactions between
-software developers.
-Planning and retrospective discussions are usually held every 1-4 weeks.
-
-Agile methods also respect the time of individuals.
-Meetings are time-boxed so that software developers can focus on the problems they are solving.
-Daily status meetings are kept to 15 minutes and planning meetings are kept to 1
-hour per week of development effort.
+- People come first: keep them happy, productive, and communicating. If a process
+  or tool isn't working for people, **change it**.
+- Favor lightweight, accessible tools over fancy, expensive packages.
+- Communicate status, issues, and lessons learned **regularly** — ideally face-to-face.
+- Protect people's time: meetings are **time-boxed** so developers can focus.
+
+::::::::::::::::::::::::::::::::::::::::::  callout
+
+## What this looks like in practice
+
+- Shared whiteboards and simple text formats (Markdown, reStructuredText) over heavy tooling.
+- Daily status meetings kept to **15 minutes**.
+- Planning kept to about **1 hour per week** of development effort.
+- A pace that can be sustained indefinitely — **without heroics**.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
 ### Working Software over Comprehensive Documentation
 
-Requirements specifications and design documents have one main purpose:  to
-help get to useful, working software.
-Customers generally don't care about them once they have their software!
+The purpose of specs and design docs is to help get to useful, working software —
+customers generally don't care about them once they have what they need. So Agile
+teams keep **"just barely enough"** documentation: enough to develop, use, and
+maintain the project, and no more. Good docs capture the **"big picture"** and the
+**"why?"** — the things you *can't* easily figure out by reading the code.
 
-Agile methods generally maintain only documentation that allows the project to
-be developed, used, and maintained, and nothing more.
-A common agile approach is "just barely enough" documentation.
-The documentation should focus on what developers can't easily figure out looking
-at the code, i.e., the "big picture," and "why?" rather than "what?"
-Work should be completed "at the latest responsible moment."
-Guards should be implemented to prevent wasted work from changing requirements.
+::::::::::::::::::::::::::::::::::::::::::  callout
 
-Agile methods generally use lightweight representations for software requirements,
-UI designs, software architecture/design, etc.:
+## Lightweight representations
 
-- a whiteboard sketch of a UI workflow or domain model
-- a 3x5 card with a brief user story described on it
-- GitHub Issues to capture feature requests as well as bugs
+- A whiteboard sketch of a UI workflow or domain model
+- A 3x5 card with a brief user story on it
+- GitHub Issues to capture feature requests and bugs
 
-### Customer Collaboration over Contract Negotiation
+::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
-If "contract negotiation" really means:  "Give me a specification of what you
-want, then leave me alone so I can go get it done," there might be a problem.
-This can occur between team members, as well as between a team and its client,
-and tends to make processes less flexible and adaptable to change.
-Agile expects requirements, or the understanding of requirements, to change!
+### Customer Collaboration over Contract Negotiation
 
-Agile methodology encourage constant collaboration within teams, and between
-developers and clients, to ensure that everyone's needs and goals are being met.
-Some agile approaches do limit opportunities for requirements to change in order
-to reduce what is called "requirements churn."
+"Contract negotiation" can quietly become: *"Give me a spec of what you want, then
+leave me alone to go build it."* That makes a project less flexible — and Agile
+**expects** requirements (or our understanding of them) to change. Instead, Agile
+encourages constant collaboration within the team and with clients so everyone's
+needs and goals stay aligned. Some approaches do deliberately limit *when*
+requirements can change, to reduce **"requirements churn."**
 
 ### Responding to Change over Following a Plan
 
-When requirements change, the current plan may no longer be the right plan.
-Agile methods adapt to change by reviewing and revising plans iteratively, over short time periods.
-Agile methods tend to only have detailed plans for the short- to medium-term.
-If (when) changes come, any effort spent on detailed long-term plans would have been wasted.
+When requirements change, the current plan may no longer be the right plan. Agile
+teams adapt by reviewing and revising plans **iteratively, over short time periods**,
+and only plan the short- to medium-term in detail. Any effort spent on detailed
+long-term plans is wasted as soon as things change — and they will.
 
 
 Now you know more about the theory around the Agile Methodology.

episodes/choosing.md

@@ -0,0 +1,101 @@
+---
+title: "Choosing a Methodology"
+teaching: 5
+exercises: 2
+---
+
+::::::::::::::::::::::::::::::::::::::: objectives
+
+- Compare the Waterfall model and Agile approaches side by side.
+- Identify the factors that make one methodology a better fit than another.
+- Recognize that real projects often blend approaches.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: questions
+
+- How do Waterfall and Agile compare?
+- Which factors should guide my choice of methodology?
+- Do I have to pick just one?
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+## Two Ends of a Spectrum
+
+You've now seen the Waterfall model and Agile frameworks like Scrum and Kanban.
+It's tempting to ask "which one is *best*?" — but the better question is "which one
+fits **this** project, **this** team, right now?"
+
+Agile does requirements gathering and design incrementally, mostly just before
+implementation. A well-executed Waterfall project can actually be *less* costly
+overall — **as long as the requirements and design don't change.** The catch, of
+course, is that they usually do.
+
+![](fig/agilevswaterfall.png){alt='A graph of project lifetime vs. effort for agile and waterfall. Waterfall has large peaks in effort at the beginning, followed by predictable iterations. Agile has smaller upfront cost but also has similar predictable iterations.'}
+
+The graph shows the trade-off: Waterfall front-loads a large planning and design
+effort, betting that it gets things right early. Agile spreads that effort out,
+accepting some ongoing cost in exchange for the ability to absorb change.
+
+## What to Weigh
+
+No single factor decides it. Look at the project as a whole:
+
+| Factor | Leans **Waterfall** | Leans **Agile** |
+|--------|---------------------|------------------|
+| Requirements clarity | Clear and complete up front | Fuzzy or still being discovered |
+| Likelihood of change | Low — stable scope | High — expect it to shift |
+| Stakeholder availability | Involved early, then hands-off | Available throughout |
+| Team size and co-location | Large, distributed, formal | Small, communicative |
+| Timeline and delivery | One big delivery at the end | Frequent, incremental releases |
+| Risk and uncertainty | Well-understood domain | Novel problem or technology |
+| Regulatory / fixed-scope needs | Strict documentation, fixed contract | Flexible scope |
+
+If most of your answers fall in the right-hand column — which is common for research
+software — an Agile approach will usually serve you better.
+
+::::::::::::::::::::::::::::::::::::::::::  callout
+
+## Research software in practice
+
+Research software rarely starts with stable requirements: the whole point is often
+to explore something nobody has built yet. That pushes most research projects toward
+Agile. But pieces of Waterfall still show up — a grant proposal is essentially an
+upfront requirements-and-design document, and a paper deadline is a fixed release
+date. Recognizing *which parts* of your project are stable and which are exploratory
+helps you apply the right approach to each.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
+## It's Not Either/Or
+
+In practice, very few teams run any methodology exactly as written. Hybrids are the norm:
+
+- **Waterfall-ish planning, Agile execution** — do enough upfront design to satisfy
+  a grant or stakeholders, then build iteratively in sprints.
+- **Scrumban** — Scrum's cadence with Kanban's flexible flow.
+- **Phase-appropriate** — a stable, well-understood component might be built
+  Waterfall-style while an experimental one is developed iteratively.
+
+The methodologies are tools, not identities. Borrow what helps and drop what gets in
+the way — which is itself a very Agile thing to do.
+
+::::::::::::::::::::::::::::::::::::::::::  discussion
+
+## Which fits your project?
+
+Think of a software project you're actually working on (or about to start).
+
+- Where do its requirements fall on the clarity/change spectrum?
+- Which approach — or blend — would fit best?
+- What's one practice from this lesson you could adopt right away?
+
+::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: keypoints
+
+- There's no universally "best" methodology — only right-sized for a given project, team, and moment.
+- Requirements clarity and likelihood of change are the biggest factors; stable scope favors Waterfall, change favors Agile.
+- Most research software leans Agile, but real projects commonly blend approaches.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::

episodes/genai.md

@@ -0,0 +1,105 @@
+---
+title: "GenAI in Project Management"
+teaching: 5
+exercises: 0
+---
+
+::::::::::::::::::::::::::::::::::::::: objectives
+
+- Identify practical ways generative AI can support project management tasks.
+- Recognize the risks and limitations of using genAI in a project workflow.
+- Understand special considerations for using genAI in research software.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: questions
+
+- Where can generative AI genuinely help with project management?
+- What are the risks of relying on it?
+- What should research software engineers keep in mind?
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+## A New Tool in the Toolbox
+
+Generative AI — large language models (LLMs) like ChatGPT, Claude, and others — has
+quickly become part of many developers' daily workflow. These tools are good at
+working with *text*, and a surprising amount of project management **is** text:
+user stories, backlogs, meeting notes, status updates, documentation.
+
+Used well, genAI can take the friction out of the routine writing-and-organizing
+parts of project management, freeing you to spend time on the parts that need human
+judgement. Used carelessly, it can introduce confident-sounding mistakes and erode
+the very communication that good project management depends on.
+
+## Where It Helps
+
+| Task | How genAI can help |
+|------|--------------------|
+| **Drafting user stories** | Turn a rough feature idea into well-formed "As a... I can..." stories |
+| **Breaking down epics** | Suggest how to decompose a large feature into sprint-sized tasks |
+| **Backlog generation** | Brainstorm candidate features or edge cases you might have missed |
+| **Estimation support** | Surface considerations that affect complexity (a starting point, not the answer) |
+| **Summarizing** | Condense standup notes, long issue threads, or a sprint's activity |
+| **Retrospectives** | Cluster feedback into themes and suggest action items |
+| **Documentation** | Draft READMEs, docstrings, changelogs, and "how to contribute" guides |
+| **Communication** | Rephrase a technical update for a non-technical stakeholder |
+
+The common thread: genAI is best as a **fast first draft** and a **brainstorming
+partner**, as long as you then review, correct, and own.
+
+## Where to Be Careful
+
+::::::::::::::::::::::::::::::::::::::::::  callout
+
+## Keep a human in the loop
+
+- **Hallucination.** LLMs can produce plausible, fluent, and *wrong* output —
+  invented requirements, mis-estimated tasks, fabricated references. Always verify.
+- **False confidence.** The polished tone makes errors easy to miss. Treat output as
+  a draft from an eager junior colleague, not an authority.
+- **Eroding communication.** Agile values *individuals and interactions*. If an
+  AI-summarized standup replaces the team actually talking, you've optimized away the
+  point of the meeting.
+- **Data, privacy, and IP.** Anything you paste into a third-party tool may leave your
+  control. Don't share confidential, sensitive, or proprietary information without
+  knowing the tool's data policy.
+- **Accountability stays human.** The AI doesn't own the deadline, the bug, or the
+  stakeholder relationship — you do.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
+## For Research Software Specifically
+
+::::::::::::::::::::::::::::::::::::::::::  callout
+
+## Research considerations
+
+- **Reproducibility and provenance.** If genAI shaped your plan, design, or docs, keep
+  a record of how. Reproducibility is a core value of research software.
+- **Disclosure.** Many journals, funders, and institutions now have policies on
+  disclosing AI use. Check them before you rely on AI-generated content in outputs.
+- **Sensitive and unpublished data.** Unpublished results, participant data, and
+  embargoed work generally should **not** go into external AI tools.
+- **Grant and reporting language.** GenAI can help draft progress reports and broader-
+  impacts text — but you remain responsible for accuracy and for meeting the funder's
+  expectations.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
+## The Bottom Line
+
+GenAI is a genuinely useful project-management assistant for the routine, text-heavy
+work — drafting, summarizing, brainstorming, reorganizing. It is **not** a substitute
+for the human judgement, communication, and accountability that make a project
+succeed. The teams that benefit most are the ones who already understand good project
+management, and use AI to do it faster — not to avoid doing it at all.
+
+:::::::::::::::::::::::::::::::::::::::: keypoints
+
+- GenAI excels at the text-heavy parts of project management: drafting stories, summarizing, and brainstorming.
+- Always verify AI output — hallucination and false confidence are real risks, and accountability stays with you.
+- For research software, mind reproducibility, disclosure policies, and never share sensitive or unpublished data with external tools.
+- GenAI augments good project management; it doesn't replace human judgement.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::