Render course

docs/01-intro.md

@@ -7,7 +7,7 @@ output: html_document
 
 # Introduction
 
-![](resources/images/01-intro_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gd422c5de97_0_0.png){width=100%}
+![](resources/images/01-intro_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gd422c5de97_0_0.png){width=100%}
 
 
 ## Motivation
@@ -20,15 +20,15 @@ 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).
 
-![](resources/images/01-intro_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_g116525eff64_0_96.png)
+![](resources/images/01-intro_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_g2def1a354ad_0_0.png)
 
 ## Topics covered:
 
-![](resources/images/01-intro_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_g11db7c97851_0_143.png){width=100%}
+![](resources/images/01-intro_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_g2def1a354ad_0_6.png){width=100%}
 
 ## Curriculum    
 
-![](resources/images/01-intro_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gd422c5de97_0_10.png)
+![](resources/images/01-intro_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gd422c5de97_0_10.png)
 
 The course includes a hands-on exercises with templates for building documentation and tutorials for cancer informatics tools.
 Individuals who take this course are encouraged to use these templates as they follow along with the course material to help increase the usability of their informatics tool.

docs/02-why_documentation.md

@@ -7,35 +7,35 @@ output: html_document
 
 # Documentation: Why it's worth the effort!
 
-![](resources/images/02-why_documentation_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gd422c5de97_0_16.png)
+![](resources/images/02-why_documentation_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gd422c5de97_0_16.png)
 
 ## The context of bioinformatics tool development
 
 Tool development is an exciting but long process -- filled with lots of careful programming, tedious troubleshooting, but also 'Aha' moments that ultimately can result in an amazing product that you should be proud of!
 
 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!
 
-![](resources/images/02-why_documentation_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_p.png)
+![](resources/images/02-why_documentation_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_p.png)
 ^[For all cartoons:     
 Avataars by https://getavataaars.com/.   
 Icons by https://thenounproject.com/ License CC BY-NC-ND 2.0.     
 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!
 
-![](resources/images/02-why_documentation_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcf14585424_0_11.png)
+![](resources/images/02-why_documentation_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcf14585424_0_11.png)
 
 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.
 
-![](resources/images/02-why_documentation_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcf14585424_0_27.png)
+![](resources/images/02-why_documentation_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcf14585424_0_27.png)
 
 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.
 
 If the tool's documentation is non-existent, scarce, out-of-date, or filled with too much jargon, the chances that Uri will be able to successfully and efficiently create a product with the tool is drastically diminished.
 
 Lack of usability often leads users to ditch even the most well-programmed of tools.
 
-![](resources/images/02-why_documentation_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcf14585424_0_60.png)
+![](resources/images/02-why_documentation_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcf14585424_0_60.png)
 
 This is the unfortunate and all-too-common result of many bioinformatics tools.
 
@@ -57,32 +57,32 @@ 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!
 
-![](resources/images/02-why_documentation_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gd228cc29d1_0_140.png)
+![](resources/images/02-why_documentation_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gd228cc29d1_0_140.png)
 
 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.
 
-![](resources/images/02-why_documentation_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcf14585424_0_47.png)
+![](resources/images/02-why_documentation_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcf14585424_0_47.png)
 
 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!
 
-![](resources/images/02-why_documentation_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcf14585424_0_112.png)
+![](resources/images/02-why_documentation_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcf14585424_0_112.png)
 
 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.
 
-![](resources/images/02-why_documentation_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcf14585424_0_144.png)
+![](resources/images/02-why_documentation_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcf14585424_0_144.png)
 
 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.
 
-![](resources/images/02-why_documentation_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcf4eaa5799_5_49.png)
+![](resources/images/02-why_documentation_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcf4eaa5799_5_49.png)
 
 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!
 
-![](resources/images/02-why_documentation_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcf4eaa5799_5_79.png)
+![](resources/images/02-why_documentation_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcf4eaa5799_5_79.png)
 
 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.
 
-![](resources/images/02-why_documentation_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcf4eaa5799_5_127.png)
+![](resources/images/02-why_documentation_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcf4eaa5799_5_127.png)
 
 Now that you are hopefully energized and ready for creating documentation for your tool, let's talk about a bit user-centered design concepts!

docs/03-lessons_from_user_designers.md

@@ -7,7 +7,7 @@ output: html_document
 
 # Lessons we should borrow from user designers
 
-![](resources/images/03-lessons_from_user_designers_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gd422c5de97_0_24.png)
+![](resources/images/03-lessons_from_user_designers_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gd422c5de97_0_24.png)
 
 ## Thinking about user-centered development
 
@@ -16,7 +16,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.
 
-![](resources/images/03-lessons_from_user_designers_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcd0e3791ab_0_0.png)
+![](resources/images/03-lessons_from_user_designers_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcd0e3791ab_0_0.png)
 ^[For all cartoons:     
 Avataars by https://getavataaars.com/.   
 Icons by https://thenounproject.com/ License CC BY-NC-ND 2.0.     
@@ -30,7 +30,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.
 
-![](resources/images/03-lessons_from_user_designers_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gd228cc29d1_0_146.png)
+![](resources/images/03-lessons_from_user_designers_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gd228cc29d1_0_146.png)
 
 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!
 
@@ -82,7 +82,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:
 
-![](resources/images/03-lessons_from_user_designers_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcd0e3791ab_0_44.png)
+![](resources/images/03-lessons_from_user_designers_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcd0e3791ab_0_44.png)
 
 Here, this figure explains how the merge function works given a particular set of ranges.
 

docs/04-good_documentation.md

@@ -7,13 +7,13 @@ output: html_document
 
 # What does good documentation look like?
 
-![](resources/images/04-good_documentation_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gd422c5de97_0_30.png)
+![](resources/images/04-good_documentation_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gd422c5de97_0_30.png)
 
 ## 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.
+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]. 
 
-![](resources/images/04-good_documentation_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcd0e3791ab_0_23.png)
+![](resources/images/04-good_documentation_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcd0e3791ab_0_23.png)
 
 ^[For all cartoons:     
 Avataars by https://getavataaars.com/.   
@@ -22,7 +22,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:
 
-![](resources/images/04-good_documentation_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcdcbd8d802_0_26.png)
+![](resources/images/04-good_documentation_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_g23b977ee2c1_0_19.png)
 
 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.
 

docs/05-getting_started_sections.md

@@ -7,13 +7,13 @@ output: html_document
 
 # Creating a smooth getting started section
 
-![](resources/images/05-getting_started_sections_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gd422c5de97_0_36.png)
+![](resources/images/05-getting_started_sections_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gd422c5de97_0_36.png)
 
 ## The goal of a getting started section
 
 A getting started section is new users' first experience with your tool. It is also can be the most frustrating experience for your user if installation doesn't happen smoothly.
 
-![](resources/images/05-getting_started_sections_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcdcbd8d4e1_0_12.png)
+![](resources/images/05-getting_started_sections_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcdcbd8d4e1_0_12.png)
 ^[For all cartoons:     
 Avataars by https://getavataaars.com/.   
 Icons by https://thenounproject.com/ License CC BY-NC-ND 2.0.     
@@ -51,15 +51,15 @@ Do some steps take more time than others? Warn them about that. Are there output
 
 Where it makes sense, you **use screenshots as assurances** to the user that they are on the right track. Being able to see that your users' screen matches what is shown in your screenshots reassures them that things are progressing correctly. Conversely, if something does not match, it can help them narrow in on a problem. _Keep in mind out-of-date screenshots can add to the confusion! -- more on tips about how to keep things up to date in a later chapter._
 
-![](resources/images/05-getting_started_sections_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gd5f2c75a67_0_79.png)
+![](resources/images/05-getting_started_sections_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gd5f2c75a67_0_79.png)
 
 Install steps should also try to address any common pitfalls, particularly **how different operating systems might require different steps**. You may consider having separate sections or pages to describe install steps on different operating systems.
 
 What dependencies does installing your tool require? Will these be installed automatically by the steps you describe or **does your user need to install other software** before being able to install your tool? This can be a big roadblock to users if dependencies and how to install them are not addressed.
 
 **To recap:**  
 
-![](resources/images/05-getting_started_sections_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcdcbd8d4e1_0_7.png)
+![](resources/images/05-getting_started_sections_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcdcbd8d4e1_0_7.png)
 
 Installation steps can be tricky -- and admittedly hard to give guidance on when individual computer' set ups can differ so much, but the more you are able to workshop your guidance to your users here, the more they will appreciate it and stick with your tool!
 
@@ -80,7 +80,7 @@ Give your users the fewest steps needed to produce a rewarding result that will
 
 This rewarding result might be a cool visual or a plot -- but also should demonstrate the most popular thing your users would like to see.
 
-![](resources/images/05-getting_started_sections_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcdcbd8d4e1_0_23.png)
+![](resources/images/05-getting_started_sections_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcdcbd8d4e1_0_23.png)
 
 ### Directs the user to the how-to examples section
 
@@ -90,11 +90,11 @@ Now that your user has successfully installed your tool and understands the basi
 
 [Snakemake has a great getting started section](https://snakemake.readthedocs.io/en/stable/getting_started/installation.html) [@Molder2021]. The makers of Snakemake tell their users how to install Snakemake using different situations and keeping dependencies in mind, right after which they have a short tutorial to entice their users!
 
-![](resources/images/05-getting_started_sections_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcdcbd8d802_0_0.png)
+![](resources/images/05-getting_started_sections_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcdcbd8d802_0_0.png)
 
 [GSEA](https://www.gsea-msigdb.org/gsea/doc/GSEAUserGuideFrame.html) introduces their users to multiple options of how they can run the tool and nicely use reassuring screenshots throughout to let their users know if they are on the right track [@Subramanian2005]!
 
-![](resources/images/05-getting_started_sections_files/figure-docx//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcdcbd8d802_0_4.png)
+![](resources/images/05-getting_started_sections_files/figure-docx//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcdcbd8d802_0_4.png)
 
 ## Exercise: Create your own getting started section!