Merge pull request #117 from jhudsl/checkLinks

add coursersa link to readme to check links

01-intro.Rmd

@@ -10,7 +10,7 @@ ottrpal::set_knitr_image_path()
 # Introduction
 
 ```{r, fig.alt="Title image: Documentation and Usability", out.width = "100%", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/export/png?id=1OU5qeRgN_fojGbcyu2qEdwlcKpDO6BveWtYW_u1Hqd4&pageid=gd422c5de97_0_0")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gd422c5de97_0_0")
 ```
 
 
@@ -25,19 +25,19 @@ Increasing the usability and quality of documentation for a tool is not only hel
 The course is intended for cancer informatics tool developers, particularly those creating tools as a part of the [Informatics Technology Cancer Research](https://itcr.cancer.gov/informatics-tools).
 
 ```{r, fig.alt = "For individuals whom: Create informatics tools, want to learn how to apply user experience design principles to their tools and want to increase the quality of their documentation", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.g116525eff64_0_96")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.g2def1a354ad_0_0")
 ```
 
 ## Topics covered:
 
 ```{r, fig.alt="Concepts discussed in Documentation and Usability course:Apply usability research concepts, Create user friendly guides, Document code clearly, Obtain helpful user feedback", out.width = "100%", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.g11db7c97851_0_143")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.g2def1a354ad_0_6")
 ```
 
 ## Curriculum    
 
 ```{r, fig.alt = "This course will demonstrate how to: Understanding why usability and documentation is vital, Identifying your user community, Building documentation and tutorials to maximize the usability of developed tools, Obtaining feedback from your users", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gd422c5de97_0_10")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gd422c5de97_0_10")
 ```
 
 The course includes a hands-on exercises with templates for building documentation and tutorials for cancer informatics tools.

02-why_documentation.Rmd

@@ -10,7 +10,7 @@ ottrpal::set_knitr_image_path()
 # Documentation: Why it's worth the effort!
 
 ```{r, fig.alt="Learning objectives This chapter will demonstrate how to:Understand good documentation increases the impact and usability of software tools. Understand good documentation is helpful for both tool developers and users.", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gd422c5de97_0_16")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gd422c5de97_0_16")
 ```
 
 ## The context of bioinformatics tool development
@@ -20,7 +20,7 @@ Tool development is an exciting but long process -- filled with lots of careful
 Tina the Tool developer, perhaps like you, has just gotten her product working well and many of the bugs have been sorted out. Tina's awesome tool is working exactly as designed and Tina is excited to get her tool out there to be used by the community!
 
 ```{r, fig.alt="Tina the Tool Developer says, After years of tedious work my informatics tool is working!. Tina’s awesome tool is a sparkling brand new.", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.p")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.p")
 ```
 ^[For all cartoons:     
 Avataars by https://getavataaars.com/.   
@@ -30,13 +30,13 @@ Emojis by OpenMoji License: CC BY-SA 4.0.]
 This is indeed cause for celebration! Perhaps researchers like Uri the Tool User will come across Tina's awesome tool and share in Tina's enthusiasm for the project! Tina's bioinformatics tool may be just what they were needing for their research project!
 
 ```{r, fig.alt="Upon finding Tina the Tool Developer’s awesome tool, Uri the Tool User says Tina’s tool is just what I need for my research project!", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gcf14585424_0_11")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gcf14585424_0_11")
 ```
 
 Uri the Tool User can't wait to apply Tina's awesome tool to their project! But, it may not be long before Uri encounters errors, or questions about Tina's awesome tool, no matter how high quality Tina's programming of the tool is.
 
 ```{r, fig.alt="Tina’s awesome tool says unintelligible warning, Error: The jargony sounding thing has encountered a problem and is on fire with the word error written all over it. Uri the Tool User is distressed and confused.", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gcf14585424_0_27")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gcf14585424_0_27")
 ```
 
 Often users like Uri, particularly in the biology and cancer fields, have little to no programming experience. Even if a user does have programming experience, they are still unfamiliar with how Tina has set up tool. The tool may even be working exactly according to Tina's vision but if users like Uri do not understand Tina's vision or basic programming principles that Tina might take for granted, it can lead to a lot of frustration and time inefficiently spent.
@@ -46,7 +46,7 @@ If the tool's documentation is non-existent, scarce, out-of-date, or filled with
 Lack of usability often leads users to ditch even the most well-programmed of tools.
 
 ```{r, fig.alt="Uri the Tool User says I have other projects due! I can’t spend more time trying to figure this tool out. Tina’s awesome tool is still on fire with errors written all over it but has been thrown in a wastebasket by Uri the Tool User. There is no documentation to help Uri the Tool user figure out how to use Tina’s awesome tool. Uri the Tool User is even more distressed and has a tear in their eye from frustration. ", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gcf14585424_0_60")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gcf14585424_0_60")
 ```
 
 This is the unfortunate and all-too-common result of many bioinformatics tools.
@@ -70,45 +70,45 @@ We realize many tool developers feel unenthused about the process of creating do
 We'd like to assure you that the effort for creating documentation has a high return payoff for the continued success of your tool as a whole!
 
 ```{r, fig.alt="Thorough and easy-to-digest documentation not only benefits users, but tool developers themselves!", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gd228cc29d1_0_140")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gd228cc29d1_0_140")
 ```
 
 Returning to our cast of characters, let's say that Tina the Tool Developer, had the time and knowledge to create awesome documentation for her tool.
 
 ```{r, fig.alt="In this next scenario, Tina the Tool Developer has skillfully created documentation that goes along with her awesome tool. The documentation is a personified document icon.", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gcf14585424_0_47")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gcf14585424_0_47")
 ```
 
 Uri the tool User is still likely to encounter errors and problems, but with thorough and easy-to-digest documentation, Uri is better equipped to troubleshoot these problems! They may also learn more about the features and limitations of the tool that will better guide Uri's next steps!
 
 ```{r, fig.alt="Uri the Tool User is again trying to use Tina’s awesome tool and encounters warnings: Tina’s tool is on fire. This time however, Tina’s documentation is present and says I can help and Uri the Tool User, though not happy, is not as frustrated as before. Although Tina the Tool Developer is not present, Tina’s documentation can help communicate to Uri how to navigate Tina’s awesome tool.", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gcf14585424_0_112")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gcf14585424_0_112")
 ```
 
 Being equipped with user-centered documentation, Uri is more likely to be able to reach the next steps of their research and potentially share a publishable result! Tina's tool is now more likely to be cited in publications, or other forms of media.
 
 ```{r, fig.alt="Uri the Tool User is enamored with Tina’s awesome tool that has awesome documentation because it has helped them wrap up their research project that is represented by a wrapped gift. Uri the Tool User says, Tina’s awesome tool saved me so much time and let me complete this awesome work!.", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gcf14585424_0_144")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gcf14585424_0_144")
 ```
 
 This rewards Uri for having used Tina's tool, making Uri not only likely to continue to use the tool for their next projects, but Uri may also help spread the word about how great their experience with Tina's tool was.
 
 ```{r, fig.alt="Uri the Tool User is telling all their colleagues how much they love Tina’s awesome tool that has documentation. Uri has a phone is posting to their professional social media accounts about how great Tina’s awesome tool and documentation is. A megaphone is pointed at a crowd. More users are informed about Tina’s awesome tool and Tina’s work is disseminated.", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gcf4eaa5799_5_49")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gcf4eaa5799_5_49")
 ```
 
 This means that Tina may have a larger user base for her tool and will help Tina with future funding opportunities and making connections that will help her create more awesome tools!
 
 Well-documented tools help developers better maintain their code in the future because they may forget the mechanics of their tool over time. If future Tina has to divert her time and effort to another project but then returns to do tool maintenance, documentation may help jog her memory!
 
 ```{r, fig.alt="Future Tina the Tool Developer now has gray hair and Tina’s awesome documentation is between Tina and Tina’s awesome tool. The documentation says It’s been awhile, let me re-introduce you to the awesome tool you made a while back!", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gcf4eaa5799_5_79")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gcf4eaa5799_5_79")
 ```
 
 Thorough and easy-to-digest documentation may also help other tool developers contribute features or fix bugs in Tina's tool. Here Colin the Contributor was able to read Tina's awesome documentation. It not only got him excited about the tool, but allowed him to program a new feature which he sent to Tina.
 
 ```{r, fig.alt="Colin the Contributor says, Tina’s documentation introduced me to the tool so well that I was excited to contribute a new feature! The feature is represented as a sparkling code. Tina the Tool Developer is excited to incorporate this new feature to the tool.", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gcf4eaa5799_5_127")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gcf4eaa5799_5_127")
 ```
 
 Now that you are hopefully energized and ready for creating documentation for your tool, let's talk about a bit user-centered design concepts!

03-lessons_from_user_designers.Rmd

@@ -10,7 +10,7 @@ ottrpal::set_knitr_image_path()
 # Lessons we should borrow from user designers
 
 ```{r, fig.alt="Learning objectives This chapter will demonstrate how to: Understand good documentation increases the impact and usability of software tools. Understand good documentation is helpful for both tool developers and users.", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gd422c5de97_0_24")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gd422c5de97_0_24")
 ```
 
 ## Thinking about user-centered development
@@ -21,7 +21,7 @@ In other words, user-centered design is an exercise in applied empathy [@deMatos
 This is why a common saying in user-centered design is "You are not your user" [@Alexakis2017]. Although it may be true that you may have a lot in common with your user, this saying is based in the idea that you should not assume your user knows what you know or thinks like you do. For example, a warning message that may seem perfectly clear to you as a developer, may be a foreign language to your user.
 
 ```{r, fig.alt="Tina the Tool Developer and Uri the Tool User both are looking at Tina’s tool that has error written all over it with a warning sign. Tina says These error messages tell me exactly what I need to know and everything is working as I intended! But Uri the Tool User says I don’t understand what I’m doing wrong these errors are unintelligible to me!", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gcd0e3791ab_0_0")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gcd0e3791ab_0_0")
 ```
 ^[For all cartoons:     
 Avataars by https://getavataaars.com/.   
@@ -37,7 +37,7 @@ As compared to yourself, your typical user may likely have a different:
 And most importantly _your user does not know your tool like you do_! You have spent many, many hours developing this tool and its unrealistic and impractical for them to spend the same number of hours with your tool that you have.
 
 ```{r, fig.alt="Your user does not know your tool like you do!", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gd228cc29d1_0_146")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gd228cc29d1_0_146")
 ```
 
 Also keep in mind users are humans in a context. Humans have demands in their life, have been working long days, and are tired/frustrated/distracted/etc. Making your tool as easy as possible to use increases the likelihood of your user continuing to stick with your tool and even becoming an advocate for your tool to their colleagues!
@@ -91,7 +91,7 @@ Humans are drawn to intuitive visuals. Visuals are efficient means of communicat
 Sometimes this is particularly helpful for complicated concepts. For example, BEDtools (@Quinlan2010) allows for the manipulation of genomic sequences in BED files. Some of these principles can be complicated to visualize, but the authors of BEDtools do a great job of using visuals to explain each function:
 
 ```{r, fig.alt="BEDtools has nice visuals with their documentation that help explain complicated subject matter. In this figure they’re showing how ranges are merged together. ", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gcd0e3791ab_0_44")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gcd0e3791ab_0_44")
 ```
 
 Here, this figure explains how the merge function works given a particular set of ranges.

04-good_documentation.Rmd

@@ -10,15 +10,15 @@ ottrpal::set_knitr_image_path()
 # What does good documentation look like?
 
 ```{r, fig.alt="Learning Objectives This chapter will demonstrate how to: Identify major components common to good documentation. Describe the purposes of components of good documentation. Set up our documentation templates for following along with the rest of this course.", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gd422c5de97_0_30")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gd422c5de97_0_30")
 ```
 
 ## Major components of good documentation
 
 In this chapter we are going to cover the major aspects of a well-documented tool. In the subsequent chapters, we will talk about each of these components in more detail, providing relevant examples and tools. Others have divided this system into different categories which we have taken inspiration from for what we describe here [@divio]. 
 
 ```{r, fig.alt="The anthropomorphic documentation has 6 major components in this illustration including: The why, getting started, how-to examples, reference guide, code comments, and user feedback.", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gcd0e3791ab_0_23")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.gcd0e3791ab_0_23")
 ```
 
 ^[For all cartoons:     
@@ -29,7 +29,7 @@ Emojis by OpenMoji License: CC BY-SA 4.0.]
 We can think of these components of documentation in terms of how much time a user has invested in learning the tool:
 
 ```{r, fig.alt="The various components of good documentation: The why, getting started, how-to examples, reference guide, code comments, and user feedback are on a continuum in that order from the most to least amount of time spent invested in a tool.", echo = FALSE}
-ottrpal::include_slide("https://docs.google.com/presentation/d/1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg/edit#slide=id.gcdcbd8d802_0_26")
+ottrpal::include_slide("https://docs.google.com/presentation/d/1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg/edit#slide=id.g23b977ee2c1_0_19")
 ```
 
 This isn't always a perfect linear timeline like this, users may use these items in a different order than we expect, but this demonstrates the intent of how users would progress through the documentation.