Feedback: summary and setup

[CarmenTamayo]

Hello @amanda-minter and @avallecam I'm reviewing the late task tutorials, and I will be raising issues to provide feedback for each specific episode. I have tried to be as thorough as possible (sorry for the long text), the tutorials are looking great- these are points to improve the user experience. On these issues, wherever questions are asked, I'm doing so from the perspective of a user, so that the changes can be added accordingly.

Let me know if you have any questions Thank you!

Part 1: Summary and setup

1. • Who is the intended audience? The 3 examples of learning personas is okay, but I wouldn't only provide that, I think it's important to first spell out clearly what the pre-requisites and target audience is, and then maybe exemplify this with the learning personas. Otherwise it might be confusing, as most people are not going to be represented by these 3 hypothetical people.
2. • When the tutorials are introduced, Epiverse-TRACE is mentioned but not referenced or explained, so unless these tutorials are delivered as part of a presentation or course delivered by Epiverse, where an introduction is made, this will be confusing for readers- are these tutorials meant to also be used as standalone materials for anyone who wants to follow them asynchronously? If so, an introduction to Epiverse or at least a link to the project would be necessary.
3. • Similarly, when the workflow of outbreak analysis tasks split into stages is introduced, there is no reference to the blogpost about the pipeline approach, or an explanation of why we are following this approach- why is it beneficial and how is this making student's life easier in terms of learning? I would include a section where this is explained as well.
4. • As a detail, the intro states that the topics covered by the tutorials are included in the diagram, however the "modelling interventions" doesn't appear on it. It says below that one or more episode will cover each topic, it would be ideal to have an expanded diagram of which episodes fit into which topic, and make sure that the names included there match the actual names of the episodes.
5. • I like the idea of a glossary of terms and the uniform structure of all the episodes of the tutorial- could the glossary be added to the index so it's easy to find and refer to when looking at a particular tutorial? 5.1. - Re the glossary, some terms that are basic concepts such as "direct transmission" are included and defined, while others are not included, e.g., ODE, but are mentioned throughout the tutorial. Is there a reason why some terms have been included and some not? If not, I think any concept, particularly those related to modelling, that are mentioned but not explained in the tutorial should definitely be included in the glossary. 5.2. - Reading the glossary, I’ve seen that it says that incubation period and latent period are synonymous- to my understanding the latent period is the period between exposure and infectiousness, and the incubation period is between exposure and symptom onset (see reference), so I would change this. 5.3. - In the same vein, I would elaborate on the definition f vector-borne tx, it's not just that infections can be passed, but that they require an organism, most commonly an arthropod, to complete their infection cycle (for instance, rabies can be transmitted to humans by dogs, but dogs are not considered vectors). Also vectors can transmit the disease between animals, not only to humans, so I’d add that so it doesn’t sound like vector borne tx is always zoonotic.
6. • Why is "outbreak analysis" capitalised?
7. • On the first sentence "…tasks aimed at learners who are willing to achieve basic competence" <- I think this sounds a bit daunting, I would say "aimed at learners who want to" instead.
8. • In the software setup- is installing R studio the only necessary step?
9. • Just a minor detail that applies to all the tutorials, the spacing between sections is sometimes a bit inconsistent, so there are some wide gaps between some sections or between text and images in an inconsistent manner, which is distracting for readers.

[avallecam]

Thank you for your comments. I'll reply to them citing each point. When needed, I'll create new issues with the "Reference in new issue" option to solve them isolated.

• Who is the intended audience? The 3 examples of learning personas is okay, but I wouldn't only provide that, I think it's important to first spell out clearly what the pre-requisites and target audience is, and then maybe exemplify this with the learning personas. Otherwise it might be confusing, as most people are not going to be represented by these 3 hypothetical people.

We can adapt the announcement page we prepared for the design of this material (reference).

Add info on:

• What will you learn? but expanded as general learning objectives (as in this reference)
• Who are these lessons for? with the learner personas.
• What is not included in this material? to help the learner decide if this is the correct material to consume or redirect them to others. here we can re-write the related projects section.

[avallecam]

• When the tutorials are introduced, Epiverse-TRACE is mentioned but not referenced or explained, so unless these tutorials are delivered as part of a presentation or course delivered by Epiverse, where an introduction is made, this will be confusing for readers- are these tutorials meant to also be used as standalone materials for anyone who wants to follow them asynchronously? If so, an introduction to Epiverse or at least a link to the project would be necessary.

So, we can create one first episode to introduce the Epiverse-TRACE approach, like the why/what/how in this tutorial. This is focused on novices, so this fits in properly.

[avallecam]

• Similarly, when the workflow of outbreak analysis tasks split into stages is introduced, there is no reference to the blogpost about the pipeline approach, or an explanation of why we are following this approach- why is it beneficial and how is this making student's life easier in terms of learning? I would include a section where this is explained as well.

This is related with #67 so we can take this into account for it.

Thank you for adding the need to cite the post (link to PR). Sadly, I did not prioritize retaking it and solving the edit suggestions there, yet. @CarmenTamayo let me know if you have time to help me finish it.

[avallecam]

• As a detail, the intro states that the topics covered by the tutorials are included in the diagram, however the "modelling interventions" doesn't appear on it. It says below that one or more episode will cover each topic, it would be ideal to have an expanded diagram of which episodes fit into which topic, and make sure that the names included there match the actual names of the episodes.

I understand your point, Currently, the roadmap diagram is a useful reference for package and tutorial development. Since we are in a pre-alpha development, we can probably keep the creation of episodes flexible, with no need to match the diagram yet. During this process, we may even split episodes if they take too much time to complete in a session or contain multiple goals that could be treated separately. Once we get to the next alpha stage of development we should evaluate the stability of the episodes and if we need to update the roadmap diagram accordingly.

[amanda-minter]

• Re the glossary, some terms that are basic concepts such as "direct transmission" are included and defined, while others are not included, e.g., ODE, but are mentioned throughout the tutorial. Is there a reason why some terms have been included and some not? If not, I think any concept, particularly those related to modelling, that are mentioned but not explained in the tutorial should definitely be included in the glossary.
• Reading the glossary, I’ve seen that it says that incubation period and latent period are synonymous- to my understanding the latent period is the period between exposure and infectiousness, and the incubation period is between exposure and symptom onset (see reference), so I would change this.
• In the same vein, I would elaborate on the definition f vector-borne tx, it's not just that infections can be passed, but that they require an organism, most commonly an arthropod, to complete their infection cycle (for instance, rabies can be transmitted to humans by dogs, but dogs are not considered vectors). Also vectors can transmit the disease between animals, not only to humans, so I’d add that so it doesn’t sound like vector borne tx is always zoonotic.

I've updated the entries for latent and incubation period, and vector borne transmission. I've also added more entries for modelling specific terms 1743b9e06843427b0a1191ad0254ade2c727ae90. We are trying to find the right balance of how much background modelling detail is needed for the tutorials, so this was useful feedback to have.

[CarmenTamayo]

Hello both, I was reading the tutorials and I wanted to comment and start a discussion on an overall issue. I was thinking that at some points it feels like the content of the episodes would fit better as a case study than a tutorial/learning material, as there is no indication of how the student should follow along, other than by reading the text. Sometimes it would be enough to say that they should copy and paste the R code and see what happens in their console/viewer, but sometimes it would be necessary to add practical exercises, where the solutions are provided but hidden until the student chooses to see them, for instance. These practical exercises could simply be slight variations from the provided question/code, but they could also include more complex questions for more advanced students. This would be a great way for readers to consolidate the knowledge that they're learning through the contents of the episodes. It seems that this was the initial approach, as a "challenge" is included in the episode "choosing an appropriate model", but it stops on subsequent episodes. Similar challenges should be introduced throughout the episodes, although, in my opinion, these could be more than one per episode, maybe an overall challenge to reproduce the whole content of the episode, and smaller exercises as described above.

I'm aware that I've raised quite a few points, I'd be very keen to meet and have a discussion, and also to contribute to updating the tutorials as well. Let me know your thoughts. Thank you!

[avallecam]

Sometimes it would be enough to say that they should copy and paste the R code and see what happens in their console/viewer, but sometimes it would be necessary to add practical exercises, where the solutions are provided but hidden until the student chooses to see them, for instance. These practical exercises could simply be slight variations from the provided question/code, but they could also include more complex questions for more advanced students. This would be a great way for readers to consolidate the knowledge that they're learning through the contents of the episodes. It seems that this was the initial approach, as a "challenge" is included in the episode "choosing an appropriate model", but it stops on subsequent episodes. Similar challenges should be introduced throughout the episodes, although, in my opinion, these could be more than one per episode, maybe an overall challenge to reproduce the whole content of the episode, and smaller exercises as described above.

Thank you for raising this up. Check the ideas and resources shared in #54 in this regard. The more contributions of exercises within an episode, the better.

[CarmenTamayo]

Thank you @avallecam , here: https://github.com/epiverse-trace/tutorials/issues/59#issuecomment-1814568915 , how would Epiverse-TRACE be introduced through a "why/what/how"? I think a section with basic information about the project in the "Summary and setup" episode would be enough

https://github.com/epiverse-trace/tutorials/issues/59#issuecomment-1814647466 here, I think regardless of whether all episodes are included to the roadmap, there should be an overview of which episodes belong to which overarching section of the pipeline (ie to each box of the plot). Further, even if not all episodes are included, I think that those that are indeed included should match the name on the roadmap.

[avallecam]

I think regardless of whether all episodes are included to the roadmap, there should be an overview of which episodes belong to which overarching section of the pipeline (ie to each box of the plot). Further, even if not all episodes are included, I think that those that are indeed included should match the name on the roadmap.

I agree with it. In #69 we shared some ideas about it. But we decided to focus first on generating the content until December, and do sth about that issue in January or before moving to alpha stage.

[avallecam]

how would Epiverse-TRACE be introduced through a "why/what/how"? I think a section with basic information about the project in the "Summary and setup" episode would be enough

Yes, it should be brief. The questions give us a structure of topics to talk about during an intro lecture with the aim of sharing our vision (why), the strategy (what), and the plan (how) for a workshop.

(I suggest continuing the conversations in the new issues I'm creating in reply to your initial comment. For example, after my reply in this comment https://github.com/epiverse-trace/tutorials/issues/59#issuecomment-1814568915 I created issue #67 )

[CarmenTamayo]

okay, although I was just referring to the point of including a couple of sentences to the "Summary and Setup" about Epiverse, not to the entire contents of the episode.

Re your point about replying on the issues, how can I know which issues have been created based on which comments? I didn't realised until you mentioned it, would it be possible to add the links to each issue on the corresponding comment? Thank you

[avallecam]

Re your point about replying on the issues, how can I know which issues have been created based on which comments? I didn't realised until you mentioned it, would it be possible to add the links to each issue on the corresponding comment? Thank you

Yes, I will tag you on each issue, I think that was the missing piece from my side!

Currently, below each comment reply, there is a row saying: "avallecam mentioned this issue" last week --> # 67 [open]

[CarmenTamayo]

that's great, thank you

[avallecam]

• In the software setup- is installing R studio the only necessary step?

I created PR #102 to fix this. @CarmenTamayo can I add you as reviewer?

[CarmenTamayo]

Hi @avallecam , I've reviewed the changes, I think it's better now, my comments are basically about keeping the content about the prerequisites of the lesson rather than trying to provide a tutorial on how to use R and other tools such as renv, I hope it's useful