carpentries-incubator / carpentries-incubator/python-intermediate-development

Episodes 3.2 & 3.3: Swap ordering?

Offen
#495 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
enhancement
Vorherrschende Sprache
TeX
Sterne
63
Forks
77
Ø Merge
20 Std. 8 Min.
Gemergte PRs (30 T.)
3

Beschreibung

Episode 3.2 feels a bit abstract and doesn't sufficiently prepare learners for the tasks they're asked to do - for example, it asks them to draw a workflow diagram for a new architecture without actually showing them any examples of workflow diagrams.

It then launches into a description of MVC interfaces, but without much context for them or illustration of why they're useful & important. If anything, the description that MVC is designed for systems with user feedback loops suggests it's irrelevant for people whose experience with scientific programming is mostly "Run simulation -> write data to CSV -> plot" or "Get data from CSV -> analyse -> plot" (which is I expect most of the audience).

We _then_ introduce Object-Orientation, but only fairly superficially, and don't illustrate existing OO systems, or provide _examples_ of the benefits they offer (just text descriptions), before asking learners to do an OO refactor.

I think it would communicate how to architect a bit better if it was structured like:

1. Objects are described, with code examples of how they help in e.g. pipelines (reference SciPy e.t.c.).
2. We do an example data flow diagram, then ask them to make a workflow diagram for this code (e.g. mentioning Yourdon diagrams)

5. We look at the DFD we made and point out which bits of data & functionality could be encapsulated, then talk about interfaces.
6. We ask them to make a class diagram for this code and describe the interfaces.
7. We get them to refactor the code to class-based, using those interfaces.
8. We introduce polymorphism, and get them to rejig it to an abstract base class + implementations.
9. We introduce the ideas of cohesion and coupling, and discuss the benefits gained from them.
10. _Then_ we introduce MVC as the way this project is structured, as a low-coupling design, and mention there are a range of other designs.

In general, IMO these sections would benefit from more diagrams and code/pseudocode, and a reduction in text. Using a 3-level example structure would help:

* **More abstract:** E.g. animal/cat/dog.
* **Generic scientific:** E.g. loading data, analysing it, and saving the output.
* **Concrete scientific:** The actual example code.

Introducing abstract concepts, then showing what that means in a scientific context, _then_ asking people to do it themselves.

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Lies die aktuellen Episoden 3.2 und 3.3 und vergleiche ihre Abfolge mit der in diesem Issue vorgeschlagenen Progression. Identifiziere, wo Diagramme, Code oder Pseudocode sowie abstrakte, allgemeine und konkrete Beispiele hinzugefügt oder neu angeordnet werden sollten. Als abgeschlossen gilt die Arbeit, wenn die Lektionen die Konzepte und Beispiele einführen, bevor sie von den Lernenden verlangen, sie anzuwenden.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
content, documentation
Issue-Typ
Dokumentation
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.