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

Episode 3.1: Framing is not suitable for audience

Aperta
#496 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
enhancement
Lingua principale
TeX
Stelle
63
Fork
77
Merge medio
20h 8m
PR unite (30g)
3

Descrizione

3.1 introduces the concept of software requirements, but does so in a way that's very focused on a clear, industry-style use case where 'Business' and 'Stakeholder' are clearly defined, and uses a pretty specific format of addressing those requirements. Then, the "consider new requirements for..." challenges are very vague and open. I can understand this being in the trials for AstraZeneca, but I think for the actual target audience of 2nd year PhD students, postdocs e.t.c. it's just not accessible. I don't think it teaches you _how_ to identify what the requirements are for a given project and what the implications of those are.

It would probably be better if we approached it from the perspective of how requirements analysis means identifying what it is that the project is actually *for*.

Business/stakeholder requirements would benefit from being redone to describe requirements in a user stories-style format, e.g. "As a researcher, I want to take data from clinicians and identify trends in patient inflammation"). We could then reference [Gherkin-format user stories](https://userpilot.com/blog/user-stories-templates/) as a way of formalising this (which also ties into things like e.g. [Cucumber](https://cucumber.io/docs/gherkin/reference). Then we can break those stories down to get the implied functionality (which then leads into the redo of architecture I proposed in #495) .

I'd also advocate for redoing the 'non-functional requirements' section into an intro to/summary of the ISO software product quality standards, getting people to consider whether those things *are* requirements for their project, and if so what they are (e.g. how performant [i]does[/i] the code need to be?). Plus emphasising understanding the importance of the requirements up-front too (e.g. so you don't sink six months into improving performance when that isn't required, or making sure you check beforehand what file types your code will *need* to inter-operate with).
![Image](https://github.com/user-attachments/assets/61c96fc8-c3ad-49a5-8754-af9d43a62343)
The current non-functional requirements section leans heavily on a challenge where most of the text space is spent describing mobile apps and embedded software, which are much more industry-focused than science-focused and lead to a bit of an implication that software requirements stuff is really just an industry thing.

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Individua il sorgente della lezione Episode 3.1 e leggi le sezioni sui requisiti aziendali/delle parti interessate e sui requisiti non funzionali, comprese le sfide relative al software mobile e embedded. Confronta l'impostazione con il pubblico di ricerca proposto, i riferimenti alle user story/Gherkin e gli standard di qualità ISO. Il lavoro è completato quando la lezione insegna l'analisi dei requisiti nei contesti di ricerca con sfide concrete e accessibili.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Ambito
content, documentation
Tipo di issue
Documentazione
Difficoltà
5/5
Tempo stimato
Più di una settimana
Stato di attività
Ferma
Chiarezza
Da chiarire
Idoneità per principianti
25/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.