Render toc-less

docs/no_toc/01-intro.md

@@ -7,7 +7,7 @@ output: html_document
 
 # Introduction
 
-<img src="resources/images/01-intro_files/figure-html//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gd422c5de97_0_0.png" title="Title image: Documentation and Usability" alt="Title image: Documentation and Usability" width="100%" />
+<img src="resources/images/01-intro_files/figure-html//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gd422c5de97_0_0.png" title="Title image: Documentation and Usability" alt="Title image: Documentation and Usability" 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).
 
-<img src="resources/images/01-intro_files/figure-html//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_g116525eff64_0_96.png" title="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" 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" width="480" />
+<img src="resources/images/01-intro_files/figure-html//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_g2def1a354ad_0_0.png" title="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" 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" width="1250" />
 
 ## Topics covered:
 
-<img src="resources/images/01-intro_files/figure-html//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_g11db7c97851_0_143.png" title="Concepts discussed in Documentation and Usability course:Apply usability research concepts, Create user friendly guides, Document code clearly, Obtain helpful user feedback" alt="Concepts discussed in Documentation and Usability course:Apply usability research concepts, Create user friendly guides, Document code clearly, Obtain helpful user feedback" width="100%" />
+<img src="resources/images/01-intro_files/figure-html//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_g2def1a354ad_0_6.png" title="Concepts discussed in Documentation and Usability course:Apply usability research concepts, Create user friendly guides, Document code clearly, Obtain helpful user feedback" alt="Concepts discussed in Documentation and Usability course:Apply usability research concepts, Create user friendly guides, Document code clearly, Obtain helpful user feedback" width="100%" />
 
 ## Curriculum    
 
-<img src="resources/images/01-intro_files/figure-html//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gd422c5de97_0_10.png" title="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" 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" width="480" />
+<img src="resources/images/01-intro_files/figure-html//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gd422c5de97_0_10.png" title="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" 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" width="1250" />
 
 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/no_toc/03-lessons_from_user_designers.md

@@ -7,7 +7,7 @@ output: html_document
 
 # Lessons we should borrow from user designers
 
-<img src="resources/images/03-lessons_from_user_designers_files/figure-html//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gd422c5de97_0_24.png" title="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." 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." width="480" />
+<img src="resources/images/03-lessons_from_user_designers_files/figure-html//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gd422c5de97_0_24.png" title="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." 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." width="1250" />
 
 ## 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.
 
-<img src="resources/images/03-lessons_from_user_designers_files/figure-html//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcd0e3791ab_0_0.png" title="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!" 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!" width="480" />
+<img src="resources/images/03-lessons_from_user_designers_files/figure-html//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcd0e3791ab_0_0.png" title="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!" 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!" width="1250" />
 ^[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.
 
-<img src="resources/images/03-lessons_from_user_designers_files/figure-html//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gd228cc29d1_0_146.png" title="Your user does not know your tool like you do!" alt="Your user does not know your tool like you do!" width="480" />
+<img src="resources/images/03-lessons_from_user_designers_files/figure-html//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gd228cc29d1_0_146.png" title="Your user does not know your tool like you do!" alt="Your user does not know your tool like you do!" width="1250" />
 
 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:
 
-<img src="resources/images/03-lessons_from_user_designers_files/figure-html//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcd0e3791ab_0_44.png" title="BEDtools has nice visuals with their documentation that help explain complicated subject matter. In this figure they’re showing how ranges are merged together. " 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. " width="480" />
+<img src="resources/images/03-lessons_from_user_designers_files/figure-html//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcd0e3791ab_0_44.png" title="BEDtools has nice visuals with their documentation that help explain complicated subject matter. In this figure they’re showing how ranges are merged together. " 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. " width="1250" />
 
 Here, this figure explains how the merge function works given a particular set of ranges.
 

docs/no_toc/04-good_documentation.md

@@ -7,13 +7,13 @@ output: html_document
 
 # What does good documentation look like?
 
-<img src="resources/images/04-good_documentation_files/figure-html//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gd422c5de97_0_30.png" title="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." 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." width="480" />
+<img src="resources/images/04-good_documentation_files/figure-html//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gd422c5de97_0_30.png" title="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." 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." width="1250" />
 
 ## 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]. 
 
-<img src="resources/images/04-good_documentation_files/figure-html//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcd0e3791ab_0_23.png" title="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." 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." width="480" />
+<img src="resources/images/04-good_documentation_files/figure-html//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_gcd0e3791ab_0_23.png" title="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." 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." width="1250" />
 
 ^[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:
 
-<img src="resources/images/04-good_documentation_files/figure-html//1cd434bkLer_CJ04GzpsZwzeEA9gjc5Ho6QimiHPbyEg_gcdcbd8d802_0_26.png" title="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." 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." width="480" />
+<img src="resources/images/04-good_documentation_files/figure-html//1PH9_KlLVggYpNJI0fgvcIcft2vDtGA_mlCqKFA8gnAg_g23b977ee2c1_0_19.png" title="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." 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." width="1250" />
 
 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.