Review Suggestions

[MicheleTobias]

After reviewing the workshop, I have the following recommendations for Sections 1-2 (I'll post 3 and 4 later):

• Introduce the concept of "Future You" (and also maybe "Past You"). It's important for people to understand that they are helping themselves with these practices and that they stand to benefit from the effort. Maybe have a scenario where a person is writing their paper for a project and finds their readme that tells them where they downloaded their data from and on what date so they can easily write their citations, or something like that. That's my number 1 time I high five Past Me.
• Idea probably for a later time: it seems like some of these practices could benefit from a template. For example, a document with headings for each section of a README, but also maybe an example document manifest that could be overwritten... I'm envisioning a folder people could download with all the things they need, kind of like our GitHub project template.
• Idea probably for a later time: It might be nice to have some stopping points to let learners try some of these things like writing out a directory structure for a project you describe or one they already are working on or planning.
• 1. Principles of Reproducibility, paragraph 2: remove or change "simply". I think you're conveying project size rather than complexity with this sentence. Document storage is far from a simple thing, especially for people who are new.
• 2.1.2. Keep Running Notes: There's a distinct bias against paper notes in this section which I feel is unwarranted. Paper notes lend themselves well to projects that have a need for creativity, diagraming, or for people who understand the world visually. Tools like Evernote (which has a free tier) let you photograph or scan your notes and they will OCR them so you can search it. Paper, digital, or both, just depends on what you need and how you like to work.
• 2.1.3. Write READMEs: Explain what "top-level" and "shallow directory structure" means for the new folks in the room.
• 2.1.3.1. File Manifests: suggest simplifying the manifest example (which is fantastic to include). Remove "[Untracked]" and the "!!", just for simplicity's sake. Out of context, these things add more questions to a new person's mind
• 2.3.1. Use Naming Conventions: suggestion to add a brief explanation of who Phil Karton is after his name in the quote. (But I totally agree with this statement!) - and any other quotes like this... Robert Martin later on, for example.
• 2.3.1. Use Naming Conventions: replace "simple" with "a form of"
• 2.3.1.1. File and Directory Names: new people don't know what a directory is. I suggest you add a sentence explaining that a directory is akin to a folder.
• - [ ] 2.3.1.1. File and Directory Names: Figure 2.1 is hard to read at 0 magnification on my external monitor. Can you move it into the main text column and make it larger? Especially since the text references. Also, give an example of the format in the text so anyone using a text reader will know what you mean.
• 2.3.2. Establish a Directory Structure: might be worth explaining what "src" is short for
• 2.4.1. Compute with Code: The intro suggests that this belongs in the "Case-by-Case Core Practices" section because it doesn't apply to all projects.
• 2.4.1. Compute with Code: "Programming is often perceived as difficult compared to using point-and-click applications. Perhaps part of the reason for this is that programming languages demand strict attention to detail" - it's more likely the "closed box" feeling: people don't know what the parameters are to put into their code and don't know where to find out about them. GUIs can be just as detailed, but you are presented with all the options visually in a GUI so you don't have to guess at what to do. I'm afraid the text that's currently there implies that GUI users lack attention to detail (or are sloppy), which I don't think you meant.
• 2.4.1. Compute with Code: consider adding references for the quotes for the programming language descriptions.

---

• After reviewing the workshop, I have the following recommendations:

• Introduce the concept of "Future You" (and also maybe "Past You"). It's important for people to understand that they are helping themselves with these practices and that they stand to benefit from the effort. Maybe have a scenario where a person is writing their paper for a project and finds their readme that tells them where they downloaded their data from and on what date so they can easily write their citations, or something like that. That's my Review Suggestions #1 time I high five Past Me.

• Idea probably for a later time: it seems like some of these practices could benefit from a template. For example, a document with headings for each section of a README, but also maybe an example document manifest that could be overwritten... I'm envisioning a folder people could download with all the things they need, kind of like our GitHub project template.

• Idea probably for a later time: It might be nice to have some stopping points to let learners try some of these things like writing out a directory structure for a project you describe or one they already are working on or planning.

• 1. Principles of Reproducibility, paragraph 2: remove or change "simply". I think you're conveying project size rather than complexity with this sentence. Document storage is far from a simple thing, especially for people who are new.

• 2.1.2. Keep Running Notes: There's a distinct bias against paper notes in this section which I feel is unwarranted. Paper notes lend themselves well to projects that have a need for creativity, diagraming, or for people who understand the world visually. Tools like Evernote (which has a free tier) let you photograph or scan your notes and they will OCR them so you can search it. Paper, digital, or both, just depends on what you need and how you like to work.

• 2.1.3. Write READMEs: Explain what "top-level" and "shallow directory structure" means for the new folks in the room.

• 2.1.3.1. File Manifests: suggest simplifying the manifest example (which is fantastic to include). Remove "[Untracked]" and the "!!", just for simplicity's sake. Out of context, these things add more questions to a new person's mind

• 2.3.1. Use Naming Conventions: suggestion to add a brief explanation of who Phil Karton is after his name in the quote. (But I totally agree with this statement!) - and any other quotes like this... Robert Martin later on, for example.

• 2.3.1. Use Naming Conventions: replace "simple" with "a form of"

• 2.3.1.1. File and Directory Names: new people don't know what a directory is. I suggest you add a sentence explaining that a directory is akin to a folder.

• - [ ] 2.3.1.1. File and Directory Names: Figure 2.1 is hard to read at 0 magnification on my external monitor. Can you move it into the main text column and make it larger? Especially since the text references. Also, give an example of the format in the text so anyone using a text reader will know what you mean.

• 2.3.2. Establish a Directory Structure: might be worth explaining what "src" is short for

• 2.4.1. Compute with Code: The intro suggests that this belongs in the "Case-by-Case Core Practices" section because it doesn't apply to all projects.

• 2.4.1. Compute with Code: "Programming is often perceived as difficult compared to using point-and-click applications. Perhaps part of the reason for this is that programming languages demand strict attention to detail" - it's more likely the "closed box" feeling: people don't know what the parameters are to put into their code and don't know where to find out about them. GUIs can be just as detailed, but you are presented with all the options visually in a GUI so you don't have to guess at what to do. I'm afraid the text that's currently there implies that GUI users lack attention to detail (or are sloppy), which I don't think you meant.

• 2.4.1. Compute with Code: Consider suggesting that people look at papers in their field to see what programming languages are more common in their field to help them make the decision about which language to start with.

[MicheleTobias]

Suggestions for Section 3:

• 3.1.1. Document the Data: It might be worth noting that metadata standards and tools vary by data type and academic field and that there are organizations that set standards for metadata. You don't necessarily need to follow them to the letter to be useful for an internal project, but if you plan to make data publicly available, you need to be aware of the standards for your type of data.

Suggestions for Section 4:

I'm assuming that Section 4 is still under development or that something hasn't been pushed to the repo, but I wanted to note that it's current public-facing state is just an outline of topics in case you were unaware. It's a good list, but it needs text.

[nick-ulle]

Thanks, these are all really helpful!

Section 4 is yet to be written, since I'm not planning to cover it in the pre-fall workshops (I think it would be a distraction to beginners). Instead, it'll go up around the same time as the next Intermediate R/Python workshops.

Also, just wondering if Carl shared the accompanying table and whether you felt any of the practices should be more or less emphasized (i.e., core vs not core) than they are?

[MicheleTobias]

@nick-ulle I did not see the table yet. That looks really good. I like how it's organized. I think it helps clarify and summarize the big block of text in the reader. I don't think I'd move anything.