Building Interactive Applications with R and Shiny (PH/JISC/TNA)

[tiagosousagarcia]

The Programming Historian has received the following tutorial on 'Building Interactive Applications with R and Shiny' by @yann-ryan. This lesson is now under review and can be read at:

http://programminghistorian.github.io/ph-submissions/en/drafts/originals/shiny-leaflet-newspaper-map-tutorial

Please feel free to use the line numbers provided on the preview if that helps with anchoring your comments, although you can structure your review as you see fit.

I will act as interim editor for the review process, until a permanent editor is assigned. The role of the editor is to solicit two reviews from the community and to manage the discussions, which should be held here on this forum.

Members of the wider community are also invited to offer constructive feedback which should post to this message thread, but they are asked to first read our Reviewer Guidelines (http://programminghistorian.org/reviewer-guidelines) and to adhere to our anti-harassment policy (below). We ask that all reviews stop after the second formal review has been submitted so that the author can focus on any revisions. I will make an announcement on this thread when that has occurred.

I will endeavor to keep the conversation open here on Github. If anyone feels the need to discuss anything privately, you are welcome to email me.

Our dedicated Ombudsperson is (Ian Milligan - http://programminghistorian.org/en/project-team). Please feel free to contact him at any time if you have concerns that you would like addressed by an impartial observer. Contacting the ombudsperson will have no impact on the outcome of any peer review.

Anti-Harassment Policy

This is a statement of the Programming Historian's principles and sets expectations for the tone and style of all correspondence between reviewers, authors, editors, and contributors to our public forums.

The Programming Historian is dedicated to providing an open scholarly environment that offers community participants the freedom to thoroughly scrutinize ideas, to ask questions, make suggestions, or to requests for clarification, but also provides a harassment-free space for all contributors to the project, regardless of gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, age or religion, or technical experience. We do not tolerate harassment or ad hominem attacks of community participants in any form. Participants violating these rules may be expelled from the community at the discretion of the editorial board. Thank you for helping us to create a safe space.

[tiagosousagarcia]

@yann-ryan, congratulations again on an excellent tutorial -- I remember a few years ago looking for something exactly like this. I've made an initial technical review (be96436), making small changes as I went along. A summary of these are:

Changes made

• l. 13 -- added wikipedia link to GUI
• l. 54 -- added link to internal copy of the data
• l. 50 -- added backticks to readme
• l. 74 -- added link to Leaflet
• l. 108 -- added 'Figure 1' to figure caption
• ll. 112-114 -- changed formating of alert
• l. 131 -- added link to internal copy of coordinates data
• l. 198 -- added 'Figure 2' to figure caption
• l. 206 -- added link to wikipedia about reactive programming
• l. 241 -- added backticks to 'sliderInput' command
• l. 268 -- added 'Figure 3' to figure caption.
• l. 336 -- embedded the link into the text
• l. 348 -- replaced user added input with capitals
• l. 430 -- added 'Figure 4' to figure caption.
• l. 506 -- added 'Figure 5' to figure caption.

Additionally, I would also suggest you consider the following (though this could be addressed when submitting corrections from reviews):

• l. 88 / Create a new RStudio Project -- add a note recommending the use of a virtual environment to prevent package conflicts, and link to a simple tutorial on how to do this

The one change we would like you to make before sending it for review is to add a conclusion to your lesson, which seems to be missing.

Thank you for all your hard work!

[drjwbaker]

@svmelton and I discussed potential editors for this article. Sarah will seek an editor from the EN team.

[yann-ryan]

Thanks @tiagosousagarcia! I'm ready to make these changes. Should I submit my updates via a pull request, or should I edit the file directly?

[svmelton]

@hawc2 has offered to serve as editor for this piece.

[drjwbaker]

Fab! @yann-ryan editing the file directly should be fine. Let me know if you have any issues (Tiago is taking some leave).

[yann-ryan]

Thanks - I've updated the file with the relevant small changes (details in the update description).

[anisa-hawes]

Hello @yann-ryan. Just to say, that I am around too – in case you have questions or need support with anything.

[hawc2]

@yann-ryan this tutorial looks solid, and I see you've already received one round of feedback. I'm going to move forward with identifying peer reviewers for this lesson. That may take a bit of time, but I'll update you once the review process has begun. Hopefully we will get you back peer reviews on this lesson by March/April.

[drjwbaker]

@hawc2 I believe @tiagosousagarcia has identified some peer reviewers already, if that would help.

[anisa-hawes]

Hello all,

Please note that this lesson's .md file has been moved to a new location within our Submissions Repository. It is now found here: https://github.com/programminghistorian/ph-submissions/tree/gh-pages/en/drafts/originals

A consequence is that this lesson's preview link has changed. It is now: http://programminghistorian.github.io/ph-submissions/en/drafts/originals/shiny-leaflet-newspaper-map-tutorial

Please let me know if you encounter any difficulties or have any questions.

Very best, Anisa

[hawc2]

@regan008 and @nlgarlic have agreed to review this lesson. We can expect to receive both reviews by March 1st. If any questions arise, please feel free to email me or post a question in this ticket. Thanks all!

[drjwbaker]

@hawc2 Did you mean 1 March here?

[hawc2]

My bad - April 1st is more like it! Thanks for catching that @drjwbaker

[anisa-hawes]

Hello @tiagosousagarcia. Re: our conversation in #418, I've just updated the asset links in this .md too.

[hawc2]

Just an update, both reviewers intend to get reviews back to you by April 15th. Thanks for your patience @yann-ryan

[regan008]

Review of Building Interactive Applications with R and Shiny

Thanks to the Programming Historian Editors (@hawc2, @anisa-hawes, and @tiagosousagarcia) for inviting me to review this tutorial. I really enjoyed reading through this and I think it’s going to be a very useful tutorial for users of the Programming Historian. This will definitely be a tutorial I refer my students to once its published.

Initial comments: As I said above, this is a valuable tutorial and I strongly believe in the value of technology like Shiny for allowing you to visualize research data. The author has made great efforts to explain the utility of this technology and has provided a useful survey of similar technology and survey of projects that use similar interactive visualizations. Further, the example data used in the tutorial is, I think, an ideal dataset for illustrating the concepts and techniques within a shiny application.

In general, my biggest piece of feedback is about the clarity of certain elements and the order in which things are explained. I’ve made a list of paragraph level places where I think the explanation could be clearer or the how & why of the code could be explained in greater detail. But to summarize, I think the author could do another pass through the tutorial and look at what is being explained where in the tutorial and ensure that terms are defined upfront.

One example of this is in the “What You’ll Learn” section. You mention reactive programing here and although you’ve explained what reactive programming is above in the introduction – you don’t actually use the term “reactive programming.” This type of thing happens frequently throughout the review and is, I think, a reflection of you knowing these concepts so well but forgetting that the average user may not know that term. I do this frequently too.

One piece from this list that I’ll pick out here has to do with the description of the UI interface. The tutorial jumps into describing the layout and formatting that layout in the code. But I think, to a user who isn’t familiar with Shiny and may or may not be familiar with web design layout principles, this section might move too fast. What would be useful here is a mockup or wireframe of how the app is envisioned before you get to the actual code. What a sidebar is and how that relates to the main panel should be explained and a link to the Shiny documentation that describes the different types of layouts that are possible would be useful. The options for layout in Shiny are limited enough that I think a bit further discussion here is warranted.

Specific items:

• Paragraph 11: The description of the data doesn’t quite match up with what I see in the repository and I think could be slightly more clear. You say “The file is available in two formats: either a .zip file containing a .csv and a readme, or as an Excel spreadsheet.” I think you could simplify this and make it a bit more clear for users unfamiliar with these file types. You might explain that a .zip file is a container that holds two files a comma separated values (csv) file and a readme file that provides details about the data. The other file is an Excel spreadsheet (xlsx) which contains the same data but …… Then explain why the csv file is perferable.
• Paragraph 23: This screenshot needs to be updated. The folder that users are directed to make in the paragraph above is called “newspaper-app” and the folder in the path shown in the image is “newspaper_map.”
• Relatedly, this image shows a file which the tutorial prompts users to download in Paragraph 27. Consider either removing that file from the screenshot or having a section earlier in the tutorial that prompts users to download all relevant files and set up their environment.
• Paragraph 30: I believe this is the first time the abbreviation ui is used. Would be useful to define this term for users.
• Paragraph 34: I think some further explanation is warranted here. Can you allude to what other layouts are possible and perhaps provide a link to the documentation so users have a visual of what it is they are coding?
• Paragraph 37: I think this is an excellent description of functions.
• Paragraph 39: This paragraph reads: “Finally, add the command to run the application itself. This is another special Shiny command, shinyApp(), with the ui and server items you’ve just made as arguments.” Referring to shinyApp() as a “command” is the right terminology here. It’s a function that produces the app as output (in other words it runs the app).
• Paragraph 42-3: I wonder if this section would be more effective if the user could see some output rather than a blank screen to verify that the command worked. Perhaps a simple hello world statement?
• Paragraph 45: really good explanation of reactive elements here.
• Paragraphs 47-49 Designing the User Interface: I think it would be useful to explain what the goal is for the layout. In particular, if you explained what a sidebar is, the user would have some sense of what they are trying to achieve with this layout code. A screenshot/wireframe would go a long way here.
• Paragraph 50: You might clarify that the starting value is essentially the default value.
• Figure 3 – very nice example!
• Code in Paragraph 65 – An explanation of how and why this filter works would be useful here.
• Paragraph 67: A join needs to be explained
• Paragraph 71: The description of inputs and outputs here is excellent and I think needs to be discussed much earlier in the tutorial as it’s a key concept.
• Somewhere you should mention how to stop the Shiny server.

[nlgarlic]

Building Interactive Applications with R and Shiny Review

Thank you for inviting me to review this tutorial, @hawc2, @anisa-hawes, and @tiagosousagarcia. I've been looking for a well-executed introduction to Shiny for a long time and this tutorial fits the bill. Like @regan008, I think Programming Historian users will find this tutorial useful.

I generally agree with @regan008 comments and will add only a few notes.

• I found the tutorial well-written and accessible overall. But I ran into an issue downloading the newspaper_coordinates.csv file. It was not included in the .zip file available at the British and Irish newspapers link in paragraph 9. Because there is no mention of this file until paragraph 22, I wasted some time backtracking through the tutorial to locate it in the Github tutorial link instead. (And the Github link does not show the file - you have to move up one directory level to find it.)

• because the R (and Shiny) terminology will be very unfamiliar to new users, I recommend deleting the last sentence of paragraph 19 which suggests that the lesson could be followed without first completing the working with R and working with the tidyverse lessons.

• starting with paragraph 45, I found the practice of explaining where to insert each code snippet difficult to follow. I found myself scrolling down to see the "full script" at the end of each segment (e.g., paragraph 53). @yann-ryan consider moving the "full script" to the beginning of each segment and then explaining what each snippet accomplishes.

• Figure 5 displays the title "Newspaper Map" but it is not included in the final script (paragraph 77) and did not appear in my output

Thanks again for inviting me to review this tutorial. I will use what I have learned here in my own projects, and imagine others will be pleased to do the same.

[tiagosousagarcia]

Many thanks to @regan008 and @nlgarlic for the reviews!

@yann-ryan, in accordance with PH process, @hawc2 will make a summary of the reviews and give you some clear instructions on how to move forward. Looking forward to seeing the final tutorial!

[yann-ryan]

Just to say thank you so much to @regan008 and @nlgarlic for your incredibly clear and helpful reviews! I look forward to hearing from @hawc2 about the next steps!

[hawc2]

Thanks so much to @regan008 and @nlgarlic for this great feedback. I agree with everything you both said. I went through this lesson myself, as I too have been wanting to get the hang of Shiny, so thank you @yann-ryan for writing this helpful tutorial.

My feedback is in line with what Amanda and Nikki said, and some of this may be slightly repetitive, but it mostly focuses on the overall arc of the lesson, signposting for each section clearly, and various stylistic approaches to make sure you weave into the lesson a slow onboarding for the reader and don't lose them as you get into the nitty gritty code.

Amanda's recommendation of a wireframe is a good idea. Of more importance is that you develop through your lesson consistent use of terminology (like 'reactive programming') so that you teach the reader a series of concepts they get a concrete sense of how to use in code by the end of the lesson.

• [ ] A couple minor points - alot of sentences include a secondary clause that begins “such as” or “including” or “for example”. As a result, alot of sentences are long, a bit run-on. Can you try to shorten some of these, breaking them into multiple sentences? When you bring up the examples in some cases, maybe describe what that example offers to your point.

• [ ] To this end, there are a lot of useful details, but in a few cases you perhaps jump into the details when you should make sure the reader has the general concepts of web design clear in their heads, and how these different frameworks/designs offer unique advantages/disadvantages. In other cases, when you say, for instance, “a new web-based language (such as D3 or Javascript),” isn’t D3 a Javascript library? In cases like this, it’s important to emphasize the fundamentals here.

• [ ] The Introduction is long, so maybe break it down into a few subsections, including advantages and disadvantages of using R for this purpose? Ideally the introduction will at least briefly mention the learning outcomes and concepts, such as reactive programming. I don’t think you need a “What you won’t learn” section, but you could put this info as a caveat in the intro perhaps? Later you use the yellow background to delineate certain types of notes, that could work well for something like this.

• [ ] In the Historical Background section, it would be helpful to clarify how the ‘newspapers’ are going to be the dataset for this lesson. You refer to them in the first paragraph as the “data”, but it’s not very clear up front what this dataset will be like. In terms of the Historical Background, what’s most relevant is what type of data is it, and how does it’s historical context/source affect what research question we can ask about it? Essentially, more of a transition from Historical Background to The Data.

• [ ] Try to structure the lesson so commentary doesn’t get in the way of the readers’ ability to follow the guided steps of the tutorial. For instance, after I visited the site to download the dataset, I had to parse the rest of the paragraph to find the final sentence that tells me to download the Zip file. First state how to get the data in simple steps, then include a separate paragraph with background commentary. I saw Amanda had similar problems with some of these basic steps.

• [ ] Similarly, it’s easy to miss the step where the reader inputs the code for “renv::activate().” Generally speaking, paragraphs can be shorter, and steps made more clear and in separate paragraphs, or numbered steps. I found it a little confusing to make the Project file, install packages, and then create a separate App.r script without those commands being included.

• [ ] Making an Application in Shiny - this section can come earlier, nearly at the start, so people knew what they were going to get out of the lesson at the start.

• [ ] The coordinates data should be downloaded with other data in The Data section, rather than once the R coding section has started.

• [ ] You could move up the Input/Output discussion currently in the Leaflet section up to the Server Logic section.

• [ ] I got lost at the Test stage. It didn’t work for me, or I couldn't tell it was working. Can you give more directions for what button to press, what to look for as a result, and how to debug? It was only once I got to the Slider section that running the code showed me anything meaningful.

• [ ] It ends up taking up a lot of space to rewrite the whole code over and over again, even if it’s helpful. Maybe that can happen less often, and there can be more signposts for each step? Generally speaking, since you’re showing the whole finished script at various stages of its development, when you tell the reader to add new code, it’s not clear where it should go (such as in the Creating the reactive leaflet map)

• [ ] Other than this, some subsections seem to be so small in headings it is hard to even see them. Ideally each section's headings will stand out more so the reader doesn't lose track of what each section is doing. Some sections have a lot of code and can be hard to follow where we are in the lesson. The last couple sections, including the Conclusion, work well, but after you've revised everything else, you may want to take some more time at the end to discuss in more detail some general conclusions about Shiny and reactive programming/web development more generally, including perhaps a mention about sustainability problems.

• [ ] The Improving the Application section too could use some more general discussion of the web design principles that these additional features offer examples of. This Improving the Application section could be better off without the bullet points so each of your additions are easier to follow and parse code steps from commentary.

Please let us know if you have questions as you go about revising this lesson. Once you've revised it, I'll ask @regan008 and @nlgarlic to take one last look at it to finalize the new version. Let us know @yann-ryan if it's feasible to do edits in the next month or so. Great work and looking forward to seeing the revised version!

[yann-ryan]

Thanks so much for this feedback @hawc2 (and again to both reviewers). I have a couple of busy weeks of work right now, but think I can realistically produce a revised version by the middle of June.

[yann-ryan]

I've just added a new version of my lesson and images to ph-submissions. Thanks again to both reviewers and @hawc2 for your feedback. I've made quite a few changes, which I'll go through here:

From @regan008:

Paragraph 11: The description of the data doesn’t quite match up with what I see in the repository and I think could be slightly more clear. You say “The file is available in two formats: either a .zip file containing a .csv and a readme, or as an Excel spreadsheet.” I think you could simplify this and make it a bit more clear for users unfamiliar with these file types. You might explain that a .zip file is a container that holds two files a comma separated values (csv) file and a readme file that provides details about the data. The other file is an Excel spreadsheet (xlsx) which contains the same data but …… Then explain why the csv file is perferable.

I've simplified the section on the data, so that both files are linked to at the same time. (paragraphs 15–17)

Paragraph 23: This screenshot needs to be updated. The folder that users are directed to make in the paragraph above is called “newspaper-app” and the folder in the path shown in the image is “newspaper_map.”

Screenshot has been updated to reflect this (paragraph 34)

Relatedly, this image shows a file which the tutorial prompts users to download in Paragraph 27. Consider either removing that file from the screenshot or having a section earlier in the tutorial that prompts users to download all relevant files and set up their environment.

I've done the latter, so that both files are downloaded at the same time. (15–17)

Paragraph 30: I believe this is the first time the abbreviation ui is used. Would be useful to define this term for users.

I've defined it in its first use (which is now in the first paragraph)

Paragraph 34: I think some further explanation is warranted here. Can you allude to what other layouts are possible and perhaps provide a link to the documentation so users have a visual of what it is they are coding?

I've done this, though I haven't gone into detail about the various options, but put in the relevant link. (53)

Paragraph 42-3: I wonder if this section would be more effective if the user could see some output rather than a blank screen to verify that the command worked. Perhaps a simple hello world statement?

Have added this. (44)

Paragraphs 47-49 Designing the User Interface: I think it would be useful to explain what the goal is for the layout. In particular, if you explained what a sidebar is, the user would have some sense of what they are trying to achieve with this layout code. A screenshot/wireframe would go a long way here.

Have added the wireframe and hopefully a clearer explanation of the layout. (54)

Paragraph 50: You might clarify that the starting value is essentially the default value.

Done (60)

Code in Paragraph 65 – An explanation of how and why this filter works would be useful here.

Have added a sentence to this effect. (74)

Paragraph 67: A join needs to be explained

Done (76)

Paragraph 71: The description of inputs and outputs here is excellent and I think needs to be discussed much earlier in the tutorial as it’s a key concept.

I've moved a section on the premise of the inputs/outputs to the introduction (8–9)

Somewhere you should mention how to stop the Shiny server.

Done. (52)

From @nlgarlic:

I found the tutorial well-written and accessible overall. But I ran into an issue downloading the newspaper_coordinates.csv file. It was not included in the .zip file available at the British and Irish newspapers link in paragraph 9. Because there is no mention of this file until paragraph 22, I wasted some time backtracking through the tutorial to locate it in the Github tutorial link instead. (And the Github link does not show the file - you have to move up one directory level to find it.)

See above, have instructed readers to download both files at the same time (still not entirely happy with the method for downloading the files from links, but this is a small technical issue). (15–17)

because the R (and Shiny) terminology will be very unfamiliar to new users, I recommend deleting the last sentence of paragraph 19 which suggests that the lesson could be followed without first completing the working with R and working with the tidyverse lessons.

Have done this.

starting with paragraph 45, I found the practice of explaining where to insert each code snippet difficult to follow. I found myself scrolling down to see the "full script" at the end of each segment (e.g., paragraph 53). @yann-ryan consider moving the "full script" to the beginning of each segment and then explaining what each snippet accomplishes.

I've done this in most cases, particularly for the final parts of the code. (see 72–73, 80)

From @hawc2:

A couple minor points - alot of sentences include a secondary clause that begins “such as” or “including” or “for example”. As a result, alot of sentences are long, a bit run-on. Can you try to shorten some of these, breaking them into multiple sentences? When you bring up the examples in some cases, maybe describe what that example offers to your point.

I think overall the tutorial should be easier to follow, but happy to take suggestions for additional places which could be clearer.

To this end, there are a lot of useful details, but in a few cases you perhaps jump into the details when you should make sure the reader has the general concepts of web design clear in their heads, and how these different frameworks/designs offer unique advantages/disadvantages. In other cases, when you say, for instance, “a new web-based language (such as D3 or Javascript),” isn’t D3 a Javascript library? In cases like this, it’s important to emphasize the fundamentals here.

The introduction has been rewritten fairly substantially, and hopefully is clearer.

The Introduction is long, so maybe break it down into a few subsections, including advantages and disadvantages of using R for this purpose? Ideally the introduction will at least briefly mention the learning outcomes and concepts, such as reactive programming. I don’t think you need a “What you won’t learn” section, but you could put this info as a caveat in the intro perhaps? Later you use the yellow background to delineate certain types of notes, that could work well for something like this.

Have implemented all these suggestions. The intro has multiple sections, the 'what you won't learn' section removed, and the learning outcomes and concepts have been moved further up into the introduction.

In the Historical Background section, it would be helpful to clarify how the ‘newspapers’ are going to be the dataset for this lesson. You refer to them in the first paragraph as the “data”, but it’s not very clear up front what this dataset will be like. In terms of the Historical Background, what’s most relevant is what type of data is it, and how does it’s historical context/source affect what research question we can ask about it? Essentially, more of a transition from Historical Background to The Data.

Have described the newspapers which make up the data. (12–13)

Try to structure the lesson so commentary doesn’t get in the way of the readers’ ability to follow the guided steps of the tutorial. For instance, after I visited the site to download the dataset, I had to parse the rest of the paragraph to find the final sentence that tells me to download the Zip file. First state how to get the data in simple steps, then include a separate paragraph with background commentary. I saw Amanda had similar problems with some of these basic steps.

I've generally re-written things in I hope clearer steps, and have given instructions to download both files at the same time.

Similarly, it’s easy to miss the step where the reader inputs the code for “renv::activate().” Generally speaking, paragraphs can be shorter, and steps made more clear and in separate paragraphs, or numbered steps. I found it a little confusing to make the Project file, install packages, and then create a separate App.r script without those commands being included.

These (and in other places) have been turned into numbered or bulleted steps. (26–29)

Making an Application in Shiny - this section can come earlier, nearly at the start, so people knew what they were going to get out of the lesson at the start.

Has been moved to the introduction (see lesson aims, paragraph 2, plus paragraphs 8–9)

The coordinates data should be downloaded with other data in The Data section, rather than once the R coding section has started.

Done (15–17)

You could move up the Input/Output discussion currently in the Leaflet section up to the Server Logic section.

I have moved a section on the input/output further up, in the introduction. I'm worried this more specific discussion will be confusing if it comes before the code itself.

I got lost at the Test stage. It didn’t work for me, or I couldn't tell it was working. Can you give more directions for what button to press, what to look for as a result, and how to debug? It was only once I got to the Slider section that running the code showed me anything meaningful.

As per recommendation by @regan008, I've added a temporary 'Hello World' message to the code before the test stage.

It ends up taking up a lot of space to rewrite the whole code over and over again, even if it’s helpful. Maybe that can happen less often, and there can be more signposts for each step? Generally speaking, since you’re showing the whole finished script at various stages of its development, when you tell the reader to add new code, it’s not clear where it should go (such as in the Creating the reactive leaflet map)

I've revised the order in which the code is presented. In the more confusing cases, I've added the code as a single chunk at the beginning of a section, and then explained each line in turn.

Other than this, some subsections seem to be so small in headings it is hard to even see them. Ideally each section's headings will stand out more so the reader doesn't lose track of what each section is doing. Some sections have a lot of code and can be hard to follow where we are in the lesson. The last couple sections, including the Conclusion, work well, but after you've revised everything else, you may want to take some more time at the end to discuss in more detail some general conclusions about Shiny and reactive programming/web development more generally, including perhaps a mention about sustainability problems.

I've removed the level 4 headings which are difficult to distinguish from regular text. As above, there are far fewer code chunks as I've combined them at the beginning of sections rather than adding them cumulatively. I have added a couple of sentences to the conclusion.

The Improving the Application section too could use some more general discussion of the web design principles that these additional features offer examples of. This Improving the Application section could be better off without the bullet points so each of your additions are easier to follow and parse code steps from commentary.

I've removed the bullet points. As per the first point: I wrote with the perspective of somebody who is somewhat familiar with programming in R and wishes to make an interactive application, either to share or to make exploratory data analysis easier. I'm not sure I'm really qualified to write a discussion of web design principles more generally!

[hawc2]

Thank you @yann-ryan! You're detailed explanation is helpful and this draft looks really good to me.

@nlgarlic and @regan008, could you take a look at Yann's revisions and let him know if there's any last edits you think he should make?

After you both sign off, I'll review it once more before handing it over to our copyeditor.

[regan008]

@yann-ryan So glad the feedback was helpful - this is an excellent addition to PH and I'm excited to recommend it to my students. @hawc2 I've had a chance to go through the new draft and I agree, this draft looks great. I think the reactive programming section and explanation really help and the wire frame really helps explain the layout of an application. Great work, consider this my thumbs up for publishing!

[hawc2]

ok let's move this forward to get published! @anisa-hawes can you copy-edit this and then I'll finish up the yaml, etc.?

[nlgarlic]

I agree. I had some difficulty getting the script to work but, overall, found the tutorial to be much improved and a great contribution.

On Aug 5, 2022, at 10:23 AM, Alex Wermer-Colan @.***> wrote:



ok let's move this forward to get published! @anisa-haweshttps://nam10.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fanisa-hawes&data=05%7C01%7Cnicole.lemire.garlic%40temple.edu%7C56121cd7e6e144f00ca408da76ee00bd%7C716e81efb52244738e3110bd02ccf6e5%7C0%7C0%7C637953061835360003%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=f40SF8nrwlpPBASq8HCURITgrhmyzvzLcoBTSyVO2lE%3D&reserved=0 can you copy-edit this and then I'll finish up the yaml, etc.?

— Reply to this email directly, view it on GitHubhttps://nam10.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fprogramminghistorian%2Fph-submissions%2Fissues%2F416%23issuecomment-1206514616&data=05%7C01%7Cnicole.lemire.garlic%40temple.edu%7C56121cd7e6e144f00ca408da76ee00bd%7C716e81efb52244738e3110bd02ccf6e5%7C0%7C0%7C637953061835516715%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=hcsf5VdBTxUCaKuG8pE2H61Oh6wuftzsiaeelCPqTto%3D&reserved=0, or unsubscribehttps://nam10.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FANJXLVDUBW5RUPLMJZOXLTDVXUPUJANCNFSM5HGXLKUA&data=05%7C01%7Cnicole.lemire.garlic%40temple.edu%7C56121cd7e6e144f00ca408da76ee00bd%7C716e81efb52244738e3110bd02ccf6e5%7C0%7C0%7C637953061835516715%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=BSGNwBQKvqt6RLVtf3AW%2F9oXPzfStN68rS%2BZIEnbEpo%3D&reserved=0. You are receiving this because you were mentioned.Message ID: @.***>

[tiagosousagarcia]

@anisa-hawes -- just a reminder that we have the budget to send this tutorial for external copyediting! Don't feel like you have to take it on, particularly as there is a series of these articles reaching this stage at the same time

[tiagosousagarcia]

Hello all -- just a quick note to say that this is my last week working for PH. It's been an absolute pleasure working on this, and I'm only sorry I'm not going to be around for its publication (from this side -- I'll definitely be reading and using it as a regular joe). Big thanks to @yann-ryan for writing it, and @hawc2 for taking it forward. Well done everyone!

[anisa-hawes]

Hello @yann-ryan 👋🏻

I've applied the copyedits + typesetting + generated perma.cc links to your lesson. Please me know if you're happy with the adjustments? See Update shiny-leaflet-newspaper-map-tutorial.md.

Note that perma.cc can't capture the interactive applications satisfactorily, so you'll see that 3x URLs at line.26 of the Markdown file remain as links to the live web.

You might have seen the Issue in Jekyll where we have recently agreed to commit to providing alt text for figure images. Your figure captions are actually so brilliantly concise and specific that they do the job alt-text would be needed for, so I'm not sure if anything additional is necessary. In this case, I think the alt-text could repeat the caption? What do you think @hawc2?

For info, the syntax to use is: {% include figure.html filename="file-name.png" alt="Visual description of figure image" caption="Caption text to display" %}. One thing to note is that Markdown styling should not be included within your alt, because screen readers read the characters directly (so bold would be read as asterisks).

Last thing:

We're introducing a new step in our workflow, asking authors and translators to complete a declaration form to acknowledge their copyright and grant us permission to publish. I'm going to email you the form now.

@hawc2, this file was missing most of its YAML so I've added that in and populated all the fields I can. The following fields remain for you to complete:

date: 2022-MM-DD
difficulty: TBC
activity: TBC
topics: [TBC]
avatar_alt: TBC
abstract: TBC
doi: TBC 

@hawc2's next steps:

• [ ] Find an image to represent the lesson. Instructions for how to prepare the image are here.
• [ ] Prepare 2 Tweets for our Twitter Bot. We'll Tweet directly after publication, but the Bot will help us to publicise the lesson in the future.
• [ ] Collaborate to resolve the outstanding question of how to set up a banner logic which will bring together lessons published as part of the PH/Jisc/TNA partnership.

Very best to all, Anisa

[yann-ryan]

Dear all,

Thanks again for all the work on this! @anisa-hawes, all these copy-edits look good to me. I'm going to email you the completed declaration form now. Let me know if I've missed anything else!

Best,

Yann.

[anisa-hawes]

Thank you @yann-ryan! I've received your Authorial-copyright-and-publishing-rights form 🙂

[jenniferisasi]

A note to say that while translating the lesson I found a link to assets that is not the correct one:

On paragraph 16, it the alternate link in "Alternatively, you can download a copy of the dataset used in this tutorial here" points to GIS coordinates, but I think you meant to link to the Newspaper titles

I'm preparing a potential different dataset but wanted to flag that one :)

[yann-ryan]

Thanks @jenniferisasi, will update this link!

[yann-ryan]

I've just updated to the correct URL as pointed out in @jenniferisasi's post. Thanks!

This lesson is currently held up as we're debugging issues relating to one of the packages (the R package sf)

[aracele]

Hello all!

While translating the lesson to Portuguese, I've found a typo in paragraph 58. It is referring to "Figure 2 above" while should be referring to "Figure 3", which is the diagram figure. I'm not sure if you are already aware of it.

[yann-ryan]

Hi @aracele , thanks so much for spotting this, I'll update the lesson text!

[yann-ryan]

It seems that problems were caused by some combination of renv and one of the necessary packages (sf), possibly only occurring on Mac OS. Following the instructions on the official repo for the package and installing the spatial analysis tool 'gdal' through the terminal with Homebrew seems to solve it. I've updated the lesson by removing the references to renv and given a link and pointer to the Github repo instructions.

I've also fixed the mistake relating to the figure reference.

I think this is now ready for a final test @hawc2!

[aracele]

It seems that problems were caused by some combination of renv and one of the necessary packages (sf), possibly only occurring on Mac OS. Following the instructions on the official repo for the package and installing the spatial analysis tool 'gdal' through the terminal with Homebrew seems to solve it. I've updated the lesson by removing the references to renv and given a link and pointer to the Github repo instructions.

I've also fixed the mistake relating to the figure reference.

I think this is now ready for a final test @hawc2!

Hi @yann-ryan, you also removed the instructions to create a project in paragraph 26, steps 1 and 2. Wouldn't it be necessary to keep these two steps since they teach how to create a project in RStudio?

[yann-ryan]

Hi @aracele, good point, I've restored the instructions!

[hawc2]

@anisa-hawes I missed a couple questions you raised before. Yes, it sounds like the alt-text could repeat the captions. We're you saying I should hold off on publishing this lesson until the banner logic question is resolved?

I can work with @yann-ryan to get the captions and a few other final things in the lesson cleaned up. I'll finalize the yaml and proceed with publication hopefully by next week

[yann-ryan]

I've just updated the alt-text for these, mostly based on the existing captions.

[anisa-hawes]

Hello @hawc2.

I've been collaborating with @jenniferisasi to see if we can resolve the banner Issue, but it isn't solved yet. The HTML Proofer Issue is getting in the way of our tests at the moment...

I've spoken to @drjwbaker and he agrees that its okay to publish a JISC/TNA lesson without the logic in place, but we'd need to hard code a banner into each file in the meantime.

[hawc2]

@anisa-hawes it looks like the banner fix is about to be done, so I'll wait till that's confirmed to move forward with this, hopefully soon!

[hawc2]

ok, I updated the lesson after a final read-through, and I contacted @yann-ryan with a couple last questions. After those last edits, we're good to go

[hawc2]

@yann-ryan your lesson is now published and live on the website!: https://programminghistorian.org/en/lessons/shiny-leaflet-newspaper-map-tutorial

Thanks @regan008 and @nlgarlic for reviewing this lesson so carefully, and to @anisa-hawes and the PH team for helping get this one published.

Conrats all!