Proposal: Aligning exercises and narrative among chapters

[k8hertweck]

Proposal

The main content of each chapter covers general concepts. Exercises appear together at the end of the chapter, and represent application of the stated concepts. Creation/development of the scripts for Zipfs Law may begin in the narrative, but in some cases may be completed in the exercises. Chapters should include references in-text to when certain "mission critical" exercises should be completed, and also include references like #310 to help make sure readers have all necessary materials for subsequent chapters.

Background

At our 2020-01-21 meeting we regrouped on assignments to rewrite the narrative of each python-rse chapter to suit the Zipfs Law narrative/ Given that conversation and the currently open exercise review issues, we realized we needed to clarify the intent and associated structure for the book. The main questions included:

• Are exercises interleaved in the text (Python Packaging exercises #304) or grouped at the end (see other exercise review issues)? Do exercises include Zipfs Law content, or only not Zipfs Law content?
• Is this book primarily by individuals working through the materials alone (used as a reference for identifying best practices), or as a textbook/lecture template for teachers?

This issue will hopefully help provide a bit more guidance and a cohesive vision as we proceed with edits. We also noted that the intro books may deviate from this plan, and that's fine given the materials may be used differently.

Pros and Cons

Pro:

• chapter order stays current, chapters easier to make consistent in length
• exercises easy to track/standardize at end of each chapter
• cognitive load lower if new data/etc don't need to be introduced for every exercise

Con:

• main code example (Zipfs Law) may deviate slightly from an authentic software development experience (e.g., may be more contrived)
• readers may accidentally skip exercises and not be prepared in subsequent chapters
• narrative may appear less coherent, because all essential code is not spelled out

Alternatives

• interleave exercises throughout the chapters (probably logistically difficult)
• use a different dataset for exercises (difficult to implement, and cognitively complex for readers)
• make the chapters more "teachable" by making all "mission critical" work included in the narrative (logistically challenging given the nature of the scripts, and would require additional modifications to the chapter order, etc

[DamienIrving]

I like the idea of leaving the option open to chapter authors to leave some of the mission critical Zipf's law code development to the exercises. We certainly don't have to do this for every chapter, but for some chapters it will make sense. If this proposal is accepted then I could update the narrative accordingly to indicate mission critical exercises.

With respect to the question of whether the book is for individuals working through the materials alone or a textbook/lecture template for teachers, I think it can and should be both.

[lwjohnst86]

@DamienIrving I agree that it can be used for both working through alone or as a template for a teacher. But the question is more, is it a reference book (mimic a resource like many traditional books) or a work-through-from-beginning-to-end book (mimic a course)?

[DamienIrving]

@lwjohnst86 I see what you're saying. Can it be both of those things too? There's a narrative that runs all the way through (so you can work through from beginning to end) but we can be careful to make sure that each chapter makes sense in isolation (e.g. by making sure it's clear where the code development got to in previous chapters).

[lwjohnst86]

Yea, I think it can be possible. I've expanded more on this in #323